swift-patterns

swift-patterns

审查、重构或构建 SwiftUI 功能，确保状态管理正确、使用现代 API、视图组合最优，并采用关注性能的模式。优先使用原生 API、遵循 Apple 设计指南，并构建易于测试的代码结构。本技能聚焦事实和最佳实践，不强制采用特定架构模式。

工作流决策树

1) 审查现有 SwiftUI 代码

→ 阅读 references/workflows-review.md，了解审查方法

• 根据属性包装器的选择检查状态管理（参见 references/state.md）
• 验证视图组合与提取模式（参见 references/view-composition.md）
• 审查列表性能与标识稳定性（参见 references/lists-collections.md）
• 验证现代 API 的使用情况（参见 references/modern-swiftui-apis.md）
• 检查使用 .task 的异步任务模式（参见 references/concurrency.md）
• 验证导航实现（参见 references/navigation.md）
• 使用审查回复模板（见下文）

2) 重构现有 SwiftUI 代码

→ 阅读 references/workflows-refactor.md，了解重构方法

• 使用操作指南提取复杂视图（参见 references/refactor-playbooks.md）
• 将已弃用的 API 迁移到现代替代方案（参见 references/modern-swiftui-apis.md）
• 优化性能热点路径（参见 references/performance.md）
• 重构状态的所有权结构（参见 references/state.md）
• 应用常见模式（参见 references/patterns.md）
• 使用重构回复模板（见下文）

3) 实现新的 SwiftUI 功能

• 首先设计数据流：识别自有状态与注入状态（参见 references/state.md）
• 组织视图，以实现最优组合（参见 references/view-composition.md）
• 仅使用现代 API（参见 references/modern-swiftui-apis.md）
• 使用 .task 修饰符处理异步任务（参见 references/concurrency.md）
• 尽早应用性能模式（参见 references/performance.md）
• 实现导航流程（参见 references/navigation.md）

4) 回答最佳实践问题

• 根据主题加载相关参考文件（见下文“参考文件”）
• 提供直接指导并附上示例

如果意图不明确，请询问：“你只想查看问题（审查），还是希望我修改代码（重构）？”

回复模板

审查回复：

1. 范围 - 审查了哪些内容
2. 发现 - 按严重程度分组，并提供可执行的说明
3. 依据 - 文件路径或代码位置
4. 风险与权衡 - 可能出现的问题或需要注意的事项
5. 后续步骤 - 优先修复或验证的内容

重构回复：

1. 意图与范围 - 要修改什么以及原因
2. 更改 - 附带文件路径的项目符号列表
3. 行为保持 - 应保持不变的内容
4. 后续步骤 - 需要进行的测试或验证

快速参考：属性包装器选择

包装器	使用场景	所有权
@State	内部视图状态（值类型或 @Observable 类）	视图拥有
@Binding	子视图需要修改父视图的状态	父视图拥有
@Bindable	注入的、需要绑定的 @Observable 对象	注入
let	来自父视图的只读值	注入
var + .onChange()	需要响应式更新的只读值	注入

关键规则：

• 始终将 @State 声明为 private（明确所有权）
• 切勿将 @State 用于传入的值（它只接受初始值）
• 将 @State 与 @Observable 类搭配使用（不要用 @StateObject）

详细说明和权衡请参见 references/state.md。

快速参考：现代 API 替代方案

已弃用	现代替代方案	说明
foregroundColor()	foregroundStyle()	支持动态类型
cornerRadius()	.clipShape(.rect(cornerRadius:))	更灵活
NavigationView	NavigationStack	类型安全的导航
tabItem()	Tab API	iOS 18+
onTapGesture()	Button	除非需要位置信息/计数
onChange(of:) { value in }	onChange(of:) { old, new in } 或 onChange(of:) { }	使用两个或零个参数
UIScreen.main.bounds	GeometryReader 或布局 API	避免硬编码尺寸

完整迁移指南请参见 references/modern-swiftui-apis.md。

审查清单

审查 SwiftUI 代码时请使用此清单：

状态管理

• 将 @State 属性标记为 private
• 传入的值不声明为 @State 或 @StateObject
• 仅在子视图会修改父视图状态时使用 @Binding
• 属性包装器的选择遵循所有权规则
• 状态所有权清晰明确

现代 API

• 不使用已弃用的修饰符（foregroundColor、cornerRadius 等）
• 使用 NavigationStack 替代 NavigationView
• 适用时使用 Button 替代 onTapGesture
• 使用双参数或无参数的 onChange()

视图组合

• 状态变化使用修饰符而非条件语句（以维持视图标识）
• 将复杂视图提取为独立子视图
• 保持视图小巧、专注
• 视图 body 简洁且纯粹（无副作用）

导航与工作表

• 使用 navigationDestination(for:) 实现类型安全的导航
• 基于模型的工作表使用 .sheet(item:)
• 工作表自行管理关闭操作

列表与集合

• ForEach 使用稳定标识（动态数据绝不使用 .indices）
• 每个 ForEach 元素对应固定数量的视图
• 不在 ForEach 中内联筛选（应预先筛选并缓存）
• 列表行中不使用 AnyView

性能

• 仅向视图传入所需的值（而非大型配置对象）
• 消除不必要的依赖
• 在高频路径中赋值状态前检查值是否变化
• 大型列表使用 LazyVStack/LazyHStack
• 不在视图 body 中创建对象

异步工作

• 使用 .task 实现自动取消
• 使用 .task(id:) 执行依赖于值的任务
• 不将 .onAppear 与异步工作混用

各项的详细说明请参见参考文件。

约束

• 仅关注 Swift/SwiftUI——除非需要桥接，否则排除服务器端 Swift 和 UIKit
• 不使用 Swift 并发模式——SwiftUI 异步工作使用 .task
• 不强制采用特定架构——不要求使用 MVVM/MVC/VIPER 或特定结构
• 不规定格式或 lint 规则——关注正确性和模式
• 不提供特定工具指导——不涉及 Xcode、Instruments 或 IDE 指南
• 允许引用： developer.apple.com/documentation/swiftui/、developer.apple.com/documentation/swift/

所有工作流都必须遵循这些约束。

理念

此技能侧重于 Apple 文档中的事实与最佳实践：

• 优先使用现代 API，而非已弃用的 API
• 明确的状态所有权模式
• 注重性能的视图组合
• 可测试的代码结构
• 不强制采用特定架构（不要求使用 MVVM/VIPER）
• 遵循 Apple 人机界面指南

参考文件

references/ 中的所有参考文件：

• workflows-review.md - 审查方法和发现分类
• workflows-refactor.md - 重构方法和不变量
• refactor-playbooks.md - 分步重构指南
• state.md - 属性包装器和所有权模式
• navigation.md - 导航实现模式
• view-composition.md - 视图结构和提取
• lists-collections.md - 标识和 ForEach 模式
• scrolling.md - 滚动处理和分页
• concurrency.md - 使用 .task 执行异步工作
• performance.md - 优化策略
• testing-di.md - 测试和依赖注入
• patterns.md - 常见的 SwiftUI 模式
• modern-swiftui-apis.md - 旧版 API 迁移
• code-review-refactoring.md - 代码质量检查