⚡

SwiftData数据持久化与架构技能Skill swift-data

这个技能专注于SwiftData在iOS开发中的数据层架构，提供最佳实践用于模块化MVVM-C应用的数据建模、持久化、同步和错误处理。关键词：SwiftData, iOS开发, 数据持久化, MVVM-C, 模块化架构, 同步策略, 错误处理

移动开发 0 次安装 0 次浏览 更新于 3/18/2026

名称: swift-data 描述: SwiftData持久化和数据层架构，适用于iOS 26 / Swift 6.2诊所模块化MVVM-C应用程序。在编写、审查或重构@Model实体、存储库实现、陈旧-同时-重新验证读取、乐观队列写入、同步/重试行为以及保持SwiftData类型仅在数据边界内的SwiftUI集成时使用。

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

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

架构对齐

这个技能强制执行与swift-ui-architect相同的模块化架构：

┌───────────────────────────────────────────────────────────────┐
│ 功能模块: 视图 + 视图模型，无SwiftData导入                     │
├───────────────────────────────────────────────────────────────┤
│ 领域: 模型 + 存储库/协调器/错误协议                           │
├───────────────────────────────────────────────────────────────┤
│ 数据: @Model实体，SwiftData存储，存储库实现，                    │
│ 远程客户端，重试执行器，同步队列，冲突处理                       │
└───────────────────────────────────────────────────────────────┘

关键原则: SwiftData类型（@Model, ModelContext, @Query, FetchDescriptor）仅存在于数据层实现代码中。功能视图/视图模型使用领域类型和协议依赖工作。

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

本技能中的所有指导都假设诊所模块化MVVM-C架构：

  • 功能模块仅导入领域 + 设计系统（从不导入数据，从不导入兄弟功能）
  • 应用目标是汇聚点，并拥有依赖容器、具体协调器和路由外壳连线
  • 领域保持纯Swift，并定义模型以及存储库、*协调、错误路由和应用错误合约
  • 数据拥有SwiftData/网络/同步/重试/后台I/O，并实现领域协议
  • 读/写流默认使用陈旧-同时-重新验证读取和乐观队列写入
  • 视图模型直接调用存储库协议（无默认用例/交互器层）

何时应用

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

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

工作流

在设计或重构基于SwiftData的功能时使用此工作流：

  1. 领域设计：定义领域结构体（Trip, Friend）和验证/计算规则（见model-domain-mapping, state-business-logic-placement）
  2. 实体设计：定义具有映射方法的@Model实体类（见model-*, model-domain-mapping）
  3. 存储库协议：在领域层定义，在数据层用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 数据建模 关键 model-
2 持久化设置 关键 persist-
3 查询与过滤 高 query-
4 CRUD操作 高 crud-
5 同步与网络 高 sync-
6 关系 中-高 rel-
7 SwiftUI状态流 中-高 state-
8 模式与迁移 中-高 schema-
9 样本数据与预览 中 preview-

快速参考

1. 数据建模（关键）

2. 持久化设置（关键）

3. 查询与过滤（高）

4. CRUD操作（高）

5. 同步与网络（高）

6. 关系（中-高）

7. SwiftUI状态流（中-高）

8. 模式与迁移（中-高）

9. 样本数据与预览（中）

如何使用

阅读个别参考文件获取详细解释和代码示例：

参考文件

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