Swift 架构技能

概述

使用该技能为 SwiftUI/UIKit 代码库选择最合适的 Swift 架构实践指南，并将其应用于用户的任务中。

工作流程

步骤 1：分析请求上下文

在选定架构前，需明确以下信息：

• 任务类型（新功能开发、重构、PR 审查、调试）
• UI 技术栈（SwiftUI、UIKit 或混合）
• 影响范围（单个页面、多个页面、全应用级别）
• 需保留的现有约定

步骤 2：选择架构

若用户明确指定了某架构，则将其作为初始候选方案，并在确认采用前执行适配性检查：

• 依据 UI 技术栈适配性（SwiftUI/UIKit/混合）、状态复杂度、副作用编排需求、团队熟悉度以及现有代码库约定进行验证
• 若适配，则按用户所选架构推进
• 若与关键约束不匹配，需明确说明不匹配点，并从 references/selection-guide.md 中推荐最接近的替代架构
• 若用户仍坚持采用不匹配的架构，则以风险缓解方案推进，并在开头清晰陈述相关风险

若用户未指定架构，则加载 references/selection-guide.md，并根据已知约束（状态复杂度、团队熟悉度、测试目标、副作用编排需求、框架偏好）推断最佳匹配架构，并简要说明推荐理由。

架构参考映射关系如下：

• MVVM → references/mvvm.md
• MVI → references/mvi.md
• TCA → references/tca.md
• Clean Architecture → references/clean-architecture.md
• VIPER → references/viper.md
• Reactive → references/reactive.md

步骤 3：分析现有代码库（如适用）

当已有代码存在时：

• 识别当前采用的架构及依赖注入（DI）风格
• 记录并发模型（async/await、Combine、GCD 或混合）
• 确保所有建议与本地约定保持一致

步骤 4：产出具体交付物

阅读所选架构的参考文档，并将其中指导原则转化为贴合用户请求的具体交付成果：

• 文件与模块结构：面向该功能的目录布局及具体文件命名
• 状态与依赖边界：具体的类型定义、协议声明及依赖注入点
• 异步策略：取消机制、Actor 隔离设计、错误处理路径
• 测试策略：应覆盖的测试范围、依赖模拟方式、示例测试结构
• 迁移路径（适用于重构场景）：从当前架构逐步迁移到目标架构的分步方案
• UI 技术栈适配：针对所选架构，SwiftUI 与 UIKit 在实现细节上的差异点说明

步骤 5：使用检查清单进行验证

最终附上参考文档中对应架构的 PR 审查检查清单，并根据用户的具体功能进行针对性调整。

输出要求

• 所有建议须严格限定于用户请求的功能或审查任务范围内。
• 优先采用基于协议的依赖注入方式，并显式建模状态。
• 标记现有代码中发现的反模式，并提供直接可落地的修复方案。
• 所有异步流程中均须包含取消机制与错误处理逻辑。
• 对于用户明确指定架构的请求，需附带简短的适配结果（fit 或 mismatch），并列出 1–2 条关键原因。
• 对于不匹配情形，须提供一个最接近的替代架构，并说明其为何更契合用户声明的约束条件。
• 编写代码时，仅包含与当前任务直接相关的模式；禁止整套照搬实践指南内容。
• 默认将参考文档中的代码片段视为示意性内容；仅当用户明确要求可运行代码时，才补充完整可编译的脚手架代码。
• 仅提出必要且阻塞性的最小化问题；其余情况应基于明确声明的假设继续推进。
• 在 PR 审查过程中，须使用对应架构的检查清单，逐条指出违规项，并提供行级修复建议。