【大前端】【iOS】iOS 真实项目可落地目录结构方案

一套 iOS 真实项目可落地目录结构方案 ，包含 模块拆分、命名规范、协作约束、演进路线。

目标：

✅ 新人 1 天能上手

✅ 3--10 人并行开发不冲突

✅ 支持后期组件化 / Swift Package

一、真实项目推荐总目录（MVVM + 模块化）

复制代码

MyApp
├── App
│   ├── AppDelegate.swift
│   ├── SceneDelegate.swift
│   ├── AppCoordinator.swift
│   ├── AppConfig.swift
│   └── Environment.swift
│
├── Modules                  # 业务模块（核心）
│   ├── Home
│   │   ├── HomeViewController.swift
│   │   ├── HomeViewModel.swift
│   │   ├── HomeModel.swift
│   │   ├── HomeService.swift
│   │   ├── HomeCoordinator.swift
│   │   └── HomeContracts.swift
│   │
│   ├── Login
│   ├── Profile
│   └── Settings
│
├── Base
│   ├── BaseViewController.swift
│   ├── BaseViewModel.swift
│   ├── BaseTableViewCell.swift
│   └── BaseCollectionViewCell.swift
│
├── Components               # 通用 UI 组件
│   ├── Alert
│   │   ├── AlertView.swift
│   │   └── AlertConfig.swift
│   │
│   ├── Loading
│   └── EmptyState
│
├── Network
│   ├── API
│   │   ├── UserAPI.swift
│   │   └── HomeAPI.swift
│   │
│   ├── NetworkManager.swift
│   ├── Request.swift
│   ├── Response.swift
│   └── NetworkError.swift
│
├── Storage
│   ├── KeychainManager.swift
│   ├── UserDefaultsStore.swift
│   └── CacheManager.swift
│
├── Utils
│   ├── Extensions
│   │   ├── UIView+Layout.swift
│   │   ├── String+Safe.swift
│   │   └── UIColor+Hex.swift
│   │
│   ├── Logger.swift
│   └── Constants.swift
│
├── Resources (Folder Reference)
│   ├── Assets.xcassets
│   ├── Fonts
│   ├── Localizable
│   │   ├── zh-Hans.strings
│   │   └── en.strings
│   └── LaunchScreen.storyboard
│
└── SupportingFiles
    ├── Info.plist
    └── PrivacyInfo.xcprivacy

二、模块内部「真实写法」详解（重点）

1️⃣ Home 模块拆解（真实项目）

复制代码

Home
├── HomeViewController.swift   # 只负责 UI & 事件
├── HomeViewModel.swift        # 状态、业务逻辑
├── HomeModel.swift            # 数据结构
├── HomeService.swift          # 网络 / 本地数据
├── HomeCoordinator.swift      # 页面跳转
└── HomeContracts.swift        # 协议定义

职责边界（避免后期失控）

文件	只允许做什么
VC	渲染 UI、绑定 ViewModel
VM	业务逻辑、状态管理
Service	API / DB / Cache
Model	struct / enum
Coordinator	push / present
Contracts	protocol

👉 绝不允许：

VC 里写网络请求
ViewModel 里 push 页面
Base 引入业务判断

三、命名规范（落地必备）

1️⃣ 文件命名

复制代码

模块名 + 职责
HomeViewController
HomeViewModel
HomeService

2️⃣ 协议命名（面试 & 架构感）

复制代码

protocol HomeViewModelInput
protocol HomeViewModelOutput
protocol HomeServiceProtocol

四、真实项目协作规则（非常重要）

1️⃣ 模块自治原则

模块 不允许互相 import
只能通过：
- Protocol
- Coordinator
- 公共组件

2️⃣ Git 冲突最小化

每人一个模块
不共享 VC
公共修改走 PR

五、网络层真实封装示例

复制代码

enum HomeAPI {
    case list
}

extension HomeAPI: APIProtocol {
    var path: String { "/home/list" }
    var method: HTTPMethod { .get }
}

final class HomeService {
    func fetchList() async throws -> [HomeModel] {
        try await NetworkManager.request(HomeAPI.list)
    }
}

六、Base & Components 的边界（真实踩坑总结）

Base 只做三件事：

生命周期兜底
通用能力（loading、toast）
统一风格

Components：

独立展示
可单独测试
可拆成 Pod / SPM

七、从单体到组件化的演进路线

阶段 1：单工程模块化

复制代码

Modules/Home
Modules/Login

阶段 2：内部组件化

复制代码

Components/Alert
Components/Loading

阶段 3：Swift Package

复制代码

MyApp
├── Packages
│   ├── HomeModule
│   ├── NetworkKit
│   └── UIComponents

👉 目录设计不变，迁移成本极低

八、真实项目「一页总结版」

iOS 真实项目目录落地三原则：

业务一定进 Modules
Base 只放能力，不放业务
能拆的迟早都会拆