SwiftData 是 Apple 的原生持久化框架，使用 @Model 类与声明式查询，构建于 Core Data 之上，专为 SwiftUI 设计。其核心原则是：引用类型（class）+ @Model 宏 + 声明式 @Query，实现响应式 SwiftUI 集成。要求 iOS 17+、Swift 5.9+，本技能聚焦 iOS 26+ 的最新特性。许可证为 Apple 专有。
一、适用场景 适合需要原生 Apple 与 SwiftUI 集成、简单 CRUD 操作、通过 @Query 自动更新 UI、CloudKit 同步（iOS 17+）、带关系的引用类型（类）的场景。若需要值类型（struct）、CloudKit 记录共享（不仅是同步）、或 50k+ 记录的大数据集特定性能需求，应考虑 SQLiteData；若需要复杂原生 SQL 或细粒度迁移控制，应考虑 GRDB。迁移相关可参考 axiom-swiftdata-migration 技能，迁移调试参考 axiom-swiftdata-migration-diag。
二、模型定义 使用 @Model 宏定义 final class（如需子类则省略 final）。可用 @Attribute(.unique) 实现类似主键的行为（CloudKit 同步不支持），需提供显式 init（SwiftData 不会自动合成），可选属性（如 String?）表示可空。@Attribute(.preserveValueOnDeletion) 用于在对象删除后仍保留其值的属性（适用于分析、审计）。
三、关系 使用 @Relationship 宏定义关系，deleteRule 可选 .cascade（级联删除）、.nullify（置空）、.deny（阻止删除）、.noAction（保持原样）。支持多对多自引用关系。关键点：SwiftData 在修改一侧时会自动管理另一侧，因此只应修改一侧，手动同时更新两侧会导致重复（尤其在 CloudKit 同步中）。取消关注时也只从一侧移除。可通过断言验证关系双向一致性。若 CloudKit 同步导致关系损坏，可备份、清空关系、从可信来源重建并强制重新同步。
四、类继承 SwiftData 支持类继承用于层级模型，基类与子类均需 @Model，基类省略 final。可用 #Predicate 中的 is 进行类型查询，用 as? 转换访问子类属性。关系可声明为基类类型以容纳混合子类实例。建议层级保持浅层（1-2 层）。
五、ModelContainer 与查询 SwiftUI App 中可用 .modelContainer(for:) 快速设置，也可自定义 ModelConfiguration（含 url、cloudKitDatabase），测试时可用 isStoredInMemoryOnly。@Query 支持过滤、排序（单个或多个 SortDescriptor）及组合，数据变化时视图自动刷新。
六、ModelContext 操作 通过 @Environment(.modelContext) 访问。支持 insert、fetch（FetchDescriptor 含 predicate 与 sortBy）、直接修改属性更新、delete、批量 delete(model:where:)、save（可选，视图消失时自动保存）。
七、谓词 #Predicate 支持基本比较、复合条件（&&、||）、字符串匹配（contains、localizedStandardContains、hasPrefix）以及关系谓词。
八、Swift 6 并发 SwiftData 模型不是 Sendable，使用 @MainActor 确保从 SwiftUI 安全访问。后台操作应使用 ModelContext(modelContainer) 创建后台上下文，而非主 actor 绑定的 @Environment(.modelContext)。
九、CloudKit 集成 通过 ModelConfiguration 的 cloudKitDatabase: .private("iCloud.com.example.App") 启用同步，需在 Xcode 中启用 iCloud 能力并选择 CloudKit、添加 iCloud 容器。SwiftData 的 CloudKit 同步是自动的，无需手动冲突解决。关键约束：使用 CloudKit 同步时，所有属性必须为可选或具有默认值（因网络时序原因），且不能使用 .unique。
十、性能与优化 技能涵盖分页查询、批量获取、限制查询、分块导入以避免内存膨胀；识别并解决 N+1 查询问题（通过预取模式可带来约 100 倍性能提升）；百万级记录的分块导入与定期保存；索引优化（何时索引频繁过滤/排序的属性，何时避免索引很少使用或频繁变化的属性，以及维护成本）。
十一、从旧框架迁移 从 Realm 或 Core Data 迁移到 SwiftData 时，可参考对比表，并遵循 realm-to-swiftdata-migration 或 axiom-swiftdata-migration 的详细指南。