SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场swift-data

swift-data

编程与开发

查看项目

更新于 10-15 09:35

技能介绍

用途

本技能是一份针对 SwiftData 的数据层架构与编码规范指南，适用于在 iOS 26 / Swift 6.2 环境下编写、审查或重构 @Model 相关代码。资料中的示例场景为采用模块化 MVVM-C 架构的 clinic 应用，内容涵盖数据建模、持久化、同步架构与错误处理。

架构约定

资料强调分层隔离，结构如下：

  • Feature 模块：包含 View 与 ViewModel，不导入 SwiftData。
  • Domain 层：纯 Swift，定义领域模型以及 repository、coordinator、error 相关协议，不依赖持久化框架。
  • Data 层：包含 @Model 实体、SwiftData store、仓储实现、远程客户端、重试执行器、同步队列与冲突处理。

关键原则是：SwiftData 类型（@Model、ModelContext、@Query、FetchDescriptor）只出现在 Data 层的实现代码中；Feature 的 View/ViewModel 面向 Domain 类型和协议依赖工作。具体约定包括：Feature 模块只导入 Domain 与 DesignSystem，不导入 Data，也不导入同级 Feature；App target 是汇聚点，持有 DependencyContainer、具体 coordinator 与 Route Shell 装配；读写默认采用 stale-while-revalidate 读取与乐观排队写入；ViewModel 直接调用仓储协议，不设默认的 use-case/interactor 层。

主要能力（规则分类）

资料将规则按优先级分为九类，并以前缀标识：

  1. 数据建模（CRITICAL，前缀 model-）：@Model 与领域结构体映射、自定义类型、实体用 class、Identifiable + UUID、自定义初始化器、计算属性、默认值、@Transient、大数据外部存储等。
  2. 持久化设置（CRITICAL，前缀 persist-）：用 Domain 仓储协议封装 SwiftData、@Model 宏、在 App 层配置 ModelContainer、容器创建失败恢复、经 @Environment 访问 ModelContext、手动 context 的 autosave、大批量遍历用 enumerate、内存配置用于测试与预览、App Groups 共享存储、@ModelActor 后台工作、跨 actor 传递 PersistentIdentifier。
  3. 查询与过滤（HIGH，前缀 query-）：@Query 声明式取数、后台插入后强制刷新、排序描述符、#Predicate 类型安全过滤、动态查询的自定义初始化器、视图外使用 FetchDescriptor、分页与 pending-change 调优、localizedStandardContains 搜索、#Expression（iOS 18+）复用谓词组件。
  4. CRUD 操作（HIGH，前缀 crud-）：经仓储插入、用 onDelete 的 IndexSet 删除、sheet 聚焦创建、取消删除避免孤儿记录、启用 undo 取消编辑、EditButton、保存完成后关闭模态、保存失败的用户反馈。
  5. 同步与网络（HIGH，前缀 sync-）：注入同步服务拉取并持久化、offline-first 设计、双向同步的冲突解决。
  6. 实体关系（MEDIUM-HIGH，前缀 rel-）：可选关系用 optional、一对多用数组、依赖 SwiftData 自动维护 inverse、级联删除规则、显式排序关系数组。
  7. SwiftUI 状态流转（MEDIUM-HIGH，前缀 state-）：经 @Observable ViewModel 访问数据、业务逻辑置于领域值类型与仓储支撑的 ViewModel、经 @Environment 注入仓储协议、@Bindable 双向绑定、@State 承载视图局部瞬时数据、提取包装视图处理动态查询状态。
  8. Schema 与迁移（MEDIUM-HIGH，前缀 schema-）：Schema 定义全部模型类型、@Attribute(.unique) 自然键、#Unique 复合唯一（iOS 18+）、#Index 热谓词与排序（iOS 18+）、变更前规划迁移、迁移恢复规划、ModelConfiguration 定制存储。
  9. 示例数据与预览（MEDIUM，前缀 preview-）：SampleData 单例、内存容器隔离、模型类型上的静态示例数据、@MainActor 标注。

使用方式（工作流）

资料给出的推荐流程为：先在 Domain 定义领域结构体与校验/计算规则；再定义 @Model 实体类及其映射方法；在 Domain 定义仓储协议并在 Data 层用 SwiftData 实现；在 App 边界一次性配置 ModelContainer 并处理错误恢复；通过 @Environment 注入仓储协议；创建 @Observable ViewModel 直接委托仓储协议；所有增删改经 ViewModel → Repository；写入排队并由同步协调器配合重试策略执行；一对多关系建模为数组并配置删除规则；用内存容器与示例数据加速预览；用带版本的 Schema 规划迁移。

适用场景

资料列出的适用时机包括：定义 @Model 实体并映射到领域结构体、在 Data 层搭建 ModelContainer 与 ModelContext、实现由 SwiftData 支撑的仓储协议、编写 stale-while-revalidate 读取（AsyncStream）、实现乐观写入与排队同步、配置实体关系、通过同步协调器从 API 拉取并持久化、处理保存失败与存储损坏及迁移错误、将 AppError 特质路由到集中式错误 UI、构建预览示例数据、规划 Schema 迁移。

限制与说明

本技能聚焦 clinic 模块化 MVVM-C 架构这一特定约定，其他架构的项目不一定直接适用。部分能力有系统版本门槛（如 #Expression、#Unique、#Index 标注为 iOS 18+），实际可用性取决于目标系统版本。资料未提供该技能本身的安装命令、收费方式、价格或独立工具形态等信息，暂未提供。