swiftdata-code-review

SwiftData 代码审查

快速参考

问题类型	参考资料
@Model、@Attribute、@Relationship、删除规则	references/model-design.md
@Query、#Predicate、FetchDescriptor、#Index	references/queries.md
@ModelActor、ModelContext、后台操作	references/concurrency.md
VersionedSchema、MigrationStage、轻量级/自定义迁移	references/migrations.md

硬性检查（报告问题前）

按顺序执行；只有通过对应检查后，才能断言存在问题。

1. 范围 — 通过条件： 已获取目标 .swift 文件路径，并确认审查范围内涉及 SwiftData（例如 import SwiftData、@Model、@Query、@ModelActor、VersionedSchema 或迁移类型）。如果均不适用，请停止审查，或用一句话缩小范围。
2. 参考资料 — 通过条件： 对于评估的每个检查清单领域（模型、查询、并发、迁移），都已打开快速参考表中对应的 references/*.md，或写明 N/A: no <area> in this review，并附上一行原因。
3. 证据 — 通过条件： 每条发现都使用从已读取文件中获取的 [FILE:LINE] ISSUE_TITLE 标题格式（允许使用行号范围）；没有引用的发现一律不报。
4. 报告 — 通过条件： 发现条目先列出引用（或将引用内嵌其中），格式为 [FILE:LINE] ISSUE_TITLE，然后再标注严重性或检查清单分组；不得陈述无引用支持的结论。

审查清单

• 将模型标记为 final（子类化会导致崩溃）
• 仅在一侧添加 @Relationship 装饰器（不能两侧都添加）
• 明确设置删除规则（不要依赖默认的 .nullify）
• 将关系初始化为空数组，而不是默认对象
• 批量插入时使用批量操作（append(contentsOf:)）
• @Query 不会在主线程加载数千个条目
• 在谓词中使用外部值时，将其捕获到局部变量中
• 在谓词中使用标量比较（而不是对象引用）
• 使用 @ModelActor 执行后台操作
• 使用 PersistentIdentifier/DTO 在 Actor 之间传递数据
• 为每个已发布版本定义 VersionedSchema
• 将 MigrationPlan 传递给 ModelContainer

何时加载参考资料

• 审查 @Model 或关系 -> model-design.md
• 审查 @Query 或 #Predicate -> queries.md
• 审查 @ModelActor 或后台工作 -> concurrency.md
• 审查架构变更或迁移 -> migrations.md

审查问题

1. 此关系赋值是否可能导致外键为 NULL？
2. 两侧都使用 @Relationship 是否会造成循环引用？
3. 此 @Query 是否可能因数据集过大而阻塞主线程？
4. 是否在不安全的情况下跨 Actor 传递模型对象？
5. 架构变更是否需要迁移计划？