Swift/SwiftUI重构技能：模块化MVVM-C架构Skill swift-refactor

---

name: swift-refactor description: 与 iOS 26 / Swift 6.2 临床模块化 MVVM-C 架构（Airbnb + OLX SPM 布局）对齐的 Swift 和 SwiftUI 重构模式。强制使用 @Observable ViewModels/协调器、应用目标 DependencyContainer + 路由外壳、领域仓库/协调器/错误路由协议，以及数据拥有的 I/O 带有陈旧-当-重新验证加上乐观队列同步边界。在将现有 SwiftUI 代码重构到临床架构时使用。

Swift/SwiftUI 重构（模块化 MVVM-C）

全面的重构指南，用于将 Swift/SwiftUI 代码迁移到模块化 MVVM-C，包含本地 SPM 包边界和应用目标组合根连接。

强制架构堆栈

┌───────────────────────────────────────────────────────────────┐
│ 应用目标：DependencyContainer、协调器、路由外壳                │
├───────────────────────────────────────────────────────────────┤
│ 功能模块：视图 + 视图模型（领域 + 设计系统依赖）              │
├───────────────────────────────────────────────────────────────┤
│ 数据包：仓库、远程/本地存储、同步、重试                       │
├───────────────────────────────────────────────────────────────┤
│ 领域包：模型、仓库/协调器/错误协议                             │
└───────────────────────────────────────────────────────────────┘

依赖规则：功能模块从不导入 数据 且从不导入兄弟功能。

临床架构合约（iOS 26 / Swift 6.2）

本技能中的所有指南假设临床模块化 MVVM-C 架构：

• 功能模块仅导入 领域 + 设计系统（从不导入 数据，从不导入兄弟功能）
• 应用目标是汇聚点，拥有 DependencyContainer、具体协调器和路由外壳连接
• 领域 保持纯 Swift，定义模型加仓库、*协调、错误路由 和 应用错误 合约
• 数据 拥有 SwiftData/网络/同步/重试/后台 I/O 并实现领域协议
• 读/写流默认为陈旧-当-重新验证读取和乐观队列写入
• 视图模型直接调用仓库协议（无默认用例/交互器层）

何时应用

参考这些指南当：

• 从已弃用的 SwiftUI API 迁移（ObservableObject、NavigationView、旧 onChange）
• 重构状态管理以使用 @Observable 视图模型
• 添加 @Equatable 差异到视图以提高性能
• 分解大视图到最多 10 节点的主体
• 重构导航到协调器 + 路由外壳模式
• 重构到领域/数据/功能/应用包边界
• 通过 DependencyContainer 设置依赖注入
• 改进列表/集合滚动性能
• 替换手动任务管理与 .task(id:) 和可取消加载

不可协商的约束（iOS 26 / Swift 6.2）

• @Observable 视图模型/协调器，ObservableObject / @Published 从不
• NavigationStack 由应用目标路由外壳和协调器拥有
• @Equatable 宏在每个视图上，AnyView 从不
• 领域定义仓库/协调器/错误路由协议；无框架耦合 I/O
• 无专用用例/交互器层；视图模型直接调用仓库协议
• 视图从不直接访问仓库

规则类别按优先级

优先级	类别	影响	前缀	规则
1	视图身份与差异	关键	diff-	4
2	API 现代化	关键	api-	7
3	状态架构	关键	state-	6
4	视图组合	高	view-	7
5	导航与协调	高	nav-	5
6	层架构	高	layer-	5
7	架构模式	高	arch-	5
8	依赖注入	中-高	di-	2
9	类型安全与协议	中-高	type-	4
10	列表与集合性能	中	list-	4
11	异步与数据流	中	data-	3
12	Swift 语言基础	中	swift-	8

快速参考

1. 视图身份与差异（关键）

• diff-equatable-views - 添加 @Equatable 宏到每个 SwiftUI 视图
• diff-closure-skip - 对闭包属性使用 @EquatableIgnored
• diff-identity-stability - 在 ForEach 中使用稳定的 O(1) 标识符
• diff-printchanges-debug - 使用 _printChanges() 诊断重新渲染

2. API 现代化（关键）

• api-observable-macro - 迁移 ObservableObject 到 @Observable 宏
• api-navigationstack-migration - 替换 NavigationView 为 NavigationStack
• api-onchange-signature - 迁移到新的 onChange 签名
• api-environment-object-removal - 替换 @EnvironmentObject 为 @Environment
• api-alert-confirmation-dialog - 迁移 Alert 到 confirmationDialog API
• api-list-foreach-identifiable - 替换 id: .self 为 Identifiable 一致性
• api-toolbar-migration - 替换 navigationBarItems 为工具栏修饰符

3. 状态架构（关键）

• state-scope-minimization - 最小化状态范围到最近消费者
• state-derived-over-stored - 使用计算属性替代冗余 @State
• state-binding-extraction - 提取 @Binding 以隔离子重新渲染
• state-remove-observation - 迁移 @ObservedObject 到 @Observable 跟踪
• state-onappear-to-task - 替换 onAppear 闭包为 .task 修饰符
• state-stateobject-placement - 迁移 @StateObject 到 @State 与 @Observable

4. 视图组合（高）

• view-extract-subviews - 提取子视图以进行差异检查点
• view-eliminate-anyview - 替换 AnyView 为 @ViewBuilder 或泛型
• view-computed-to-struct - 将计算视图属性转换为结构视图
• view-modifier-extraction - 提取重复修饰符到自定义 ViewModifiers
• view-conditional-content - 使用 Group 或条件修饰符替代条件视图
• view-preference-keys - 替换回调闭包为 PreferenceKey
• view-body-complexity - 减少视图主体到最多 10 节点

5. 导航与协调（高）

• nav-centralize-destinations - 重构导航到协调器模式
• nav-value-based-links - 替换 NavigationLink 为协调器路由
• nav-path-state-management - 使用 NavigationPath 进行编程导航
• nav-split-view-adoption - 使用 NavigationSplitView 用于多列布局
• nav-sheet-item-pattern - 替换布尔表触发为项目绑定

6. 层架构（高）

• layer-dependency-rule - 提取领域层，零框架导入
• layer-usecase-protocol - 移除用例/交互器层；保留编排在视图模型 + 仓库协议
• layer-repository-protocol - 仓库协议在领域，实现在数据
• layer-no-view-repository - 移除视图直接访问仓库
• layer-viewmodel-boundary - 重构视图模型以仅暴露显示准备状态

7. 架构模式（高）

• arch-viewmodel-elimination - 重构内联状态为 @Observable 视图模型
• arch-protocol-dependencies - 通过视图模型层提取协议依赖
• arch-environment-key-injection - 使用环境键进行服务注入
• arch-feature-module-extraction - 提取功能到独立模块
• arch-model-view-separation - 提取业务逻辑到领域模型和仓库支持的视图模型

8. 依赖注入（中-高）

• di-container-composition - 在应用根组合依赖容器
• di-mock-testing - 为每个协议依赖添加模拟实现

9. 类型安全与协议（中-高）

• type-tagged-identifiers - 替换字符串 ID 为标记类型
• type-result-over-optionals - 使用 Result 类型替代带错误标志的可选
• type-phantom-types - 使用幻影类型进行编译时状态机
• type-force-unwrap-elimination - 用安全替代消除强制解包

10. 列表与集合性能（中）

• list-constant-viewcount - 确保 ForEach 为每个元素产生常量视图计数
• list-filter-in-model - 将过滤/排序逻辑从 ForEach 移动到视图模型
• list-lazy-stacks - 替换 VStack/HStack 为惰性变体用于无界内容
• list-id-keypath - 提供显式 id 键路径 — 从不依赖隐式身份

11. 异步与数据流（中）

• data-task-modifier - 替换 onAppear 异步工作为 .task 修饰符
• data-error-loadable - 建模加载状态为枚举替代布尔标志
• data-cancellation - 使用 .task 自动取消 — 从不手动管理任务

12. Swift 语言基础（中）

• swift-let-vs-var - 使用 let 为常量，var 为变量
• swift-structs-vs-classes - 优先使用结构体替代类
• swift-camel-case-naming - 使用驼峰命名约定
• swift-string-interpolation - 使用字符串插值用于动态文本
• swift-functions-clear-names - 为函数和参数命名清晰
• swift-for-in-loops - 使用 for-in 循环用于集合
• swift-optionals - 安全处理可选类型与解包
• swift-closures - 使用闭包用于内联函数

如何使用

阅读个别参考文件以获取详细解释和代码示例：

• 部分定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板