ios-architecture-expert

iOS Architecture Expert — Clean Modular Architecture（iOS 架构专家）是一个指导 iOS/Swift 应用架构设计、结构划分、重构与评审的 AI 技能。

一、用途 该技能用于在用户设计、组织、重构或评审 iOS/Swift 应用架构时提供规则与参考。核心目标是建立清晰的分层与模块边界，使功能模块与 UI 框架解耦，并让依赖装配集中在 Composition Root。

二、主要能力

1. Agent 行为契约：

• 功能（Feature）模块不得引入 UIKit/SwiftUI，只能依赖 Foundation。领域模型、use case、presenter 以及 API/缓存逻辑不依赖 UI 框架。
• 每一层之间的转换都要定义边界（protocol 或 closure），某一层不得引用另一层的具体类型。当存在多种策略时使用 protocol（如 FeedStore、HTTPClient、ResourceView、FeedCache）；当只有一种策略时使用组合 closure。
• 领域模型使用值类型：struct、Hashable、Sendable，不使用 class。
• Presentation 逻辑与框架无关，presenter 输出 view model（struct），presentation 层不出现 UIImage、UIColor 或 SwiftUI 类型。
• 所有依赖装配发生在 Composition Root（app target 或专用的 CompositionRoot 模块）；功能模块不自行创建依赖。
• 测试驱动设计：每个 use case 一个测试类，按行为命名（如 CacheFeedUseCaseTests），并在每个测试类中使用 makeSUT() 工厂。
• 只测试公共 API：Composition Root 之外不使用 @testable import，测试目标使用普通 import。
• 使用 SPM 多目标（multi-target）包进行模块分离：Feed（Foundation）、FeediOS（UIKit）、App（组合）。
• 异步操作优先使用 async/await 而非闭包/Combine。在部署目标允许时（iOS 26+）使用 Task.immediate；更早目标回退到普通 Task 并让测试等待可观察状态。
• 匹配项目既有测试框架；新项目默认使用 Swift Testing。
• 共享可变状态用 @MainActor 标注：presenter、adapter、view controller 与组合代码运行在主 actor 上。
• 不要为只有单一实现且没有第二种策略迹象的边界添加 protocol，改为在 Composition Root 中组合 closure。

1. 架构诊断表：以“症状 → 首要检查 → 最小安全修复 → 深入文档”的形式给出常见问题的定位与修复方向，涵盖：功能模块引入 UIKit/SwiftUI、presentation 模式选择、view controller 职责过多、presentation 逻辑重复、单一实现的 protocol、单例问题、共享 API client、请求前连通性检查、@MainActor 类型竞态、Storyboard 属性注入、use case 查询与状态变更混杂、空方法体 conformance、领域模型含 Codable/@Model/CodingKeys、横切关注点重复、presenter 与 view 的循环引用、CoreData 启动崩溃、刷新时重复网络请求、测试依赖真实基础设施、组合边界 Sendable 警告、分页加载失败、缓存校验未执行、生产组合中的调试代码、SwiftUI 依赖装配位置等。

2. Gotchas（易错点）：列举实现细节中的常见陷阱，包括 Task.immediate 的可用性、CoreDataFeedStore 以 /dev/null 作为 storeURL 的特性、@Sendable 闭包中的捕获方式、iOS 26 中 UIWindow 初始化废弃、didEndDisplaying 的取消方式、Diffable data source 与 Dynamic Type 刷新、Thread.isMainThread 的语义、NSManagedObjectModel 缓存、未应用首个 snapshot 时无 section、adjustsFontForContentSizeCategory 默认值、NSKeyValueObservation 的持有、diffable data source 提前请求 cell、@MainActor 类型经非隔离同步 protocol 要求后失去隔离、URLSession 对 delegate 的强引用、URLSessionConfiguration 创建会话后的修改无效、Task 与 AnyCancellable 的差异等。

3. 架构分层：以表格定义 Feature、API、Cache、Presentation、UI（UIKit）、UI（SwiftUI）、Composition 各层职责。判断代码归属的依据是逻辑类型：应用特定（use case）、应用无关（业务模型与策略）、框架（基础设施），而非文件夹名称。

4. 关键模式速查：列出 Adapter、Decorator、Composite、Interception、Null Object、LoadResourcePresenter、WeakRefVirtualProxy、LoadResourcePresentationAdapter、FeedViewAdapter、Paginated、Composition Root / FeedService、Scheduler protocol、InMemoryFeedStore、LoaderSpy、Specification Pattern、UI Composer、Static Mapper、Cache Policy、CellController 等模式的用途。

5. 功能决策树：从定义领域模型、添加并发标注、获取远端数据、持久化、展示、选择 UIKit/SwiftUI、装配、验证并发等步骤给出新建功能的推荐路径。

6. Guardrails（护栏）：列出一系列禁止项，包括不在功能模块中创建具体类型、不直接取用 .shared、不在功能模块引用 DI 容器/coordinator/router、不在请求前检查连通性、不给领域类型与 store protocol 加 @MainActor、不使用 @unchecked Sendable、不把缓存策略嵌入 loader、不在 view controller 放导航逻辑、不使用 @testable import、不基于单一客户端做泛化、不在组件中编码内存管理策略、不让功能模块依赖 Composition Root、复杂度不足时不引入 coordinator/router/DI 容器、不因某个实现是异步就把领域或 store 边界改成异步等。并建议非架构类并发问题交由 swift-language-expert 技能处理。

7. 验证清单：在实现或评审时给出检查项（原文该部分内容未完整提供）。

三、使用方式 该技能的安装方式、触发命令、运行环境与配置方法在给定资料中暂未提供。资料仅包含其规则、表格、模式与清单内容，URL 为 https://www.skills.sh/swiftyjourney/ios-architecture-expert-skill/ios-architecture-expert。

四、适用场景 适用于 iOS/Swift 项目的架构设计、模块与分层拆分、依赖管理与组合根装配、presentation 模式选择、并发边界处理与可测试性设计，以及现有工程的重构与架构评审。

五、限制 该技能是一套架构规则与参考，并非具体实现代码库；其中涉及的部分行为（如测试访问级别）被明确说明为“刻意比源代码库更严格”。资料未提供收费、价格、平台支持范围与效果保证等信息，这些内容暂未提供。