swift-code-review

Swift 代码审查

审查工作流

按以下顺序执行。下方每项通过条件满足之前，不要输出审查发现。

1. Swift / 工具链基线 — 确定语言和工具链环境：Package.swift 中的 // swift-tools-version，以及清单中的各目标 Swift 语言版本或 swiftSettings；对于 Xcode，检查项目或目标构建设置中的 SWIFT_VERSION（或等效设置）；注明审查是否仅针对单个文件。
   通过条件： 在提出依赖严格并发、仅用于迁移的语法或 SDK 可用性的建议之前，先明确说明具体的 Swift 语言版本或模式（例如，Swift 6 语言模式、tools 5.10）。

2. 阅读周边代码 — 对每个有更改的 .swift 文件，阅读包含这些更改的完整外围类型、函数、方法或属性，而不只是 diff 片段。
   通过条件： 每个有更改的文件至少阅读了一个包含更改的完整外围符号（类型或成员）。

3. 确定检查清单范围 — 使用快速参考，判断审查检查清单中的哪些条目和参考资料适用；打开相应参考文件；跳过与 diff 明显无关的条目。
   通过条件： 审查（或工作笔记）列出已检查的领域，或将不适用的领域标记为 N/A，并附上一句与 diff 相关的理由（例如“更改中没有 SwiftUI / @Observable”）。

4. 报告前验证 — 加载并遵循review-verification-protocol。
   通过条件： 对于每项准备报告的发现，均满足该技能中的硬性关卡（按顺序执行）（阅读完整符号、将“未使用”判定前搜索用法、将“缺少处理”判定前检查调用方、校准严重性、提供 [FILE:LINE] 证据）。

硬性关卡（顺序相同，表述更简洁）

步骤	客观通过条件
1	在提出依赖版本或 SDK 的建议之前，记录 Swift 版本/模式（或明确说明仅审查单个文件的限制）。
2	阅读每个有更改文件的完整外围符号，而不只是 diff。
3	列出检查清单范围及参考资料，或标记为 N/A 并附上与 diff 相关的理由。
4	对每项报告的问题，完成 review-verification-protocol。

输出格式

按以下格式报告发现：

[FILE:LINE] ISSUE_TITLE
Severity: Critical | Major | Minor | Informational
Description of the issue and why it matters.

快速参考

问题类型	参考资料
async/await、actors、Sendable、Task	references/concurrency.md
@Observable、@ObservationIgnored、@Bindable	references/observable.md
throws、Result、try?、typed throws	references/error-handling.md
强制解包、保留环、命名	references/common-mistakes.md

审查检查清单

• 不对运行时数据（网络、用户输入、文件）使用强制解包（!）
• 存储为属性的闭包使用 [weak self]
• 代理属性为 weak
• 相互独立的异步操作使用 async let 或 TaskGroup
• 长时间运行的 Task 检查 Task.isCancelled
• Actor 有需要保护的可变状态（避免无状态 actor）
• Sendable 类型确实是线程安全的（注意 @unchecked）
• 显式处理错误（不留空的 catch 块）
• 自定义错误遵循 LocalizedError，并提供描述性消息
• 嵌套的 @Observable 对象也标记为 @Observable
• 对 Observable 对象进行双向绑定时使用 @Bindable

何时加载参考资料

• 审查 async/await、actors 或 TaskGroup → concurrency.md
• 审查 @Observable 或 SwiftUI 状态 → observable.md
• 审查错误处理或 throws → error-handling.md
• 通用 Swift 审查 → common-mistakes.md

审查问题

1. 可并发运行的异步操作是否使用了 async let？
2. Actor 状态是否可能在挂起点之间发生变化（重入问题）？
3. @unchecked Sendable 是否有实际的同步机制作为保障？
4. 是否记录错误并提供有帮助的上下文？
5. 闭包或代理是否可能造成保留环？