swift-data

SwiftData 最佳实践 — 模块化 MVVM-C 数据层

SwiftData 数据建模、持久化、同步架构和错误处理的全面指南，与诊所模块化 MVVM-C 技术栈保持一致。

架构对齐

此技能遵循 swift-ui-architect 规定的相同模块化架构：

┌───────────────────────────────────────────────────────────────┐
│ Feature modules: View + ViewModel, no SwiftData imports       │
├───────────────────────────────────────────────────────────────┤
│ Domain: models + repository/coordinator/error protocols        │
├───────────────────────────────────────────────────────────────┤
│ Data: @Model entities, SwiftData stores, repository impls,     │
│ remote clients, retry executor, sync queue, conflict handling  │
└───────────────────────────────────────────────────────────────┘

核心原则： SwiftData 类型（@Model、ModelContext、@Query、FetchDescriptor）仅存在于 Data 层的实现代码中。功能模块的视图/视图模型使用 Domain 类型和协议依赖。

诊所架构约定（iOS 26 / Swift 6.2）

此技能中的所有指导均以诊所模块化 MVVM-C 架构为前提：

• 功能模块仅导入 Domain + DesignSystem（绝不导入 Data，也不导入同级功能模块）
• App 目标是汇合点，拥有 DependencyContainer、具体协调器和 Route Shell 接线
• Domain 保持纯 Swift，定义模型以及仓库、*Coordinating、ErrorRouting 和 AppError 约定
• Data 负责 SwiftData/网络/同步/重试/后台 I/O，并实现 Domain 协议
• 读写流程默认采用过期后重新验证读取和乐观排队写入
• 视图模型直接调用仓库协议（默认不设用例/交互器层）

适用场景

在以下情况下参考这些指南：

• 定义 @Model 实体类并将其映射到领域结构体
• 在 Data 层设置 ModelContainer 和 ModelContext
• 实现由 SwiftData 支持的仓库协议
• 编写过期后重新验证的仓库读取（AsyncStream）
• 实现乐观写入和排队同步操作
• 配置实体关系（一对多、反向关系）
• 从 API 获取数据，并通过同步协调器持久化到 SwiftData
• 处理保存失败、存储损坏和迁移错误
• 将 AppError 特征路由到集中式错误 UI 基础设施
• 使用示例数据构建预览基础设施
• 规划应用更新的架构迁移

工作流

设计或重构由 SwiftData 支持的功能时，请使用此工作流：

1. Domain 设计：定义带有验证/计算规则的领域结构体（Trip、Friend）（参见 model-domain-mapping、state-business-logic-placement）
2. 实体设计：定义带有映射方法的 @Model 实体类（参见 model-*、model-domain-mapping）
3. 仓库协议：在 Domain 层定义，在 Data 层使用 SwiftData 实现（参见 persist-repository-wrapper）
4. 容器接线：在应用边界配置一次 ModelContainer，并提供错误恢复（参见 persist-container-setup、persist-container-error-recovery）
5. 依赖注入：通过 @Environment 注入仓库协议（参见 state-dependency-injection）
6. 视图模型：创建直接委托给仓库协议的 @Observable 视图模型（参见 state-query-vs-viewmodel）
7. CRUD 流程：所有插入/删除/更新操作都通过视图模型 -> 仓库路由（参见 crud-*）
8. 同步架构：将写入操作排队，通过带重试策略的同步协调器执行（参见 sync-*）
9. 关系：将多对多关系建模为数组；定义删除规则（参见 rel-*）
10. 预览：创建内存容器和示例数据，以便快速迭代（参见 preview-*）
11. 架构演进：使用版本化架构规划迁移（参见 schema-*）

故障排除

• 数据未持久化 -> persist-model-macro、persist-container-setup、persist-autosave、schema-configuration
• 后台导入后列表未更新 -> query-background-refresh、persist-model-actor
• 列表未更新（同一上下文）-> query-property-wrapper、state-wrapper-views
• API 同步产生重复项 -> schema-unique-attributes、sync-conflict-resolution
• 更改模型后应用在启动时崩溃 -> schema-migration-recovery、persist-container-error-recovery
• 保存失败且数据悄然丢失 -> crud-save-error-handling
• 网络数据过时 -> sync-offline-first、sync-fetch-persist
• 小组件/扩展无法查看数据 -> persist-app-group、schema-configuration
• 为数据视图选择架构模式 -> state-query-vs-viewmodel、persist-repository-wrapper

按优先级划分的规则类别

优先级	类别	影响	前缀
1	数据建模	CRITICAL	model-
2	持久化设置	CRITICAL	persist-
3	查询与筛选	HIGH	query-
4	CRUD 操作	HIGH	crud-
5	同步与网络	HIGH	sync-
6	关系	MEDIUM-HIGH	rel-
7	SwiftUI 状态流	MEDIUM-HIGH	state-
8	架构与迁移	MEDIUM-HIGH	schema-
9	示例数据与预览	MEDIUM	preview-

快速参考

1. 数据建模（CRITICAL）

• model-domain-mapping - 在 Domain/Data 边界之间将 @Model 实体映射到领域结构体
• model-custom-types - 使用自定义类型，而不是并行数组
• model-class-for-persistence - 将类用于 SwiftData 实体类型
• model-identifiable - 让实体遵循 Identifiable，并使用 UUID
• model-initializer - 为实体类提供自定义初始化器
• model-computed-properties - 使用计算属性表示派生数据
• model-defaults - 为实体属性提供合理的默认值
• model-transient - 使用 @Transient 标记非持久化属性
• model-external-storage - 为大型二进制数据使用外部存储

2. 持久化设置（CRITICAL）

• persist-repository-wrapper - 通过 Domain 仓库协议封装 SwiftData
• persist-model-macro - 对所有持久化类型应用 @Model 宏
• persist-container-setup - 在 App 层级配置 ModelContainer
• persist-container-error-recovery - 通过存储恢复机制处理 ModelContainer 创建失败
• persist-context-environment - 通过 @Environment 访问 ModelContext（Data 层）
• persist-autosave - 为手动创建的上下文启用自动保存
• persist-enumerate-batch - 使用 ModelContext.enumerate 执行大规模遍历
• persist-in-memory-config - 为测试和预览使用内存配置
• persist-app-group - 使用 App Groups 共享数据存储
• persist-model-actor - 使用 @ModelActor 在后台执行 SwiftData 操作
• persist-identifier-transfer - 在 Actor 之间传递 PersistentIdentifier

3. 查询与筛选（高）

• query-property-wrapper - 使用 @Query 声明式获取数据（数据层）
• query-background-refresh - 后台上下文插入数据后强制刷新视图
• query-sort-descriptors - 将排序描述符应用于 @Query
• query-predicates - 使用 #Predicate 进行类型安全的筛选
• query-dynamic-init - 使用自定义视图初始化器实现动态查询
• query-fetch-descriptor - 在 SwiftUI 视图之外使用 FetchDescriptor
• query-fetch-tuning - 调整 FetchDescriptor 的分页和待处理更改行为
• query-localized-search - 使用 localizedStandardContains 进行搜索
• query-expression - 使用 #Expression 创建可复用的谓词组件（iOS 18+）

4. CRUD 操作（高）

• crud-insert-context - 通过仓库实现插入模型
• crud-delete-indexset - 使用 onDelete 提供的 IndexSet 通过仓库删除数据
• crud-sheet-creation - 使用工作表通过 ViewModel 专注创建数据
• crud-cancel-delete - 仅在保存时持久化数据，避免产生孤立记录
• crud-undo-cancel - 启用撤销功能，并用它取消编辑
• crud-edit-button - 提供 EditButton 以管理列表
• crud-dismiss-save - ViewModel 完成保存后关闭模态视图
• crud-save-error-handling - 在仓库保存失败时向用户提供反馈

5. 同步与网络（高）

• sync-fetch-persist - 使用注入的同步服务获取并持久化 API 数据
• sync-offline-first - 通过仓库读取和后台同步设计离线优先架构
• sync-conflict-resolution - 实现双向同步的冲突解决机制

6. 关系（中高）

• rel-optional-single - 使用可选类型表示可选关系
• rel-array-many - 使用数组表示一对多关系
• rel-inverse-auto - 依靠 SwiftData 自动维护反向关系
• rel-delete-rules - 为拥有的关系配置级联删除规则
• rel-explicit-sort - 显式排序关系数组

7. SwiftUI 状态流（中高）

• state-query-vs-viewmodel - 通过 @Observable ViewModel 处理所有数据访问
• state-business-logic-placement - 将业务逻辑放在领域值类型和由仓库支持的 ViewModel 中
• state-dependency-injection - 通过 @Environment 注入仓库协议
• state-bindable - 使用 @Bindable 实现模型的双向绑定
• state-local-state - 使用 @State 存储视图本地的临时数据
• state-wrapper-views - 提取包装视图以处理动态查询状态

8. 架构与迁移（中高）

• schema-define-all-types - 使用所有模型类型定义架构
• schema-unique-attributes - 使用 @Attribute(.unique) 设置自然键
• schema-unique-macro - 使用 #Unique 实现复合唯一性（iOS 18+）
• schema-index - 对高频谓词和排序使用 #Index（iOS 18+）
• schema-migration-plan - 更改模型前规划迁移
• schema-migration-recovery - 为架构变更规划迁移恢复
• schema-configuration - 使用 ModelConfiguration 自定义存储

9. 示例数据与预览（中）

• preview-sample-singleton - 为预览创建 SampleData 单例
• preview-in-memory - 使用内存容器隔离预览
• preview-static-data - 在模型类型上定义静态示例数据
• preview-main-actor - 为 SampleData 标注 @MainActor

使用方法

阅读单个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息