⚠️

重要前提

安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →

SwiftData 最佳实践：模块化 MVVM-C 数据层架构、持久化与同步指南

swift-data by pproenca/dot-skills

63 周安装量

97 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/pproenca/dot-skills --skill swift-data

iOS Swift 系统架构

🇨🇳中文介绍

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

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

架构对齐

本技能强制执行与 swift-ui-architect 所要求的相同模块化架构：

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

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

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

PostgreSQL表设计最佳实践：核心规则、数据类型选择与常见陷阱详解

13,000 周安装

API设计指南：REST/GraphQL设计原则、规范文档与版本控制策略

11,500 周安装

Android 整洁架构指南：模块化设计、依赖注入与数据层实现

1,600 周安装

Laravel架构模式指南：生产级开发模式与最佳实践

1,400 周安装

功能模块仅导入 Domain 和 DesignSystem（绝不导入 Data，也绝不导入同级功能模块）
应用目标是汇聚点，拥有 DependencyContainer、具体协调器和路由外壳的连线
Domain 保持纯 Swift，定义模型以及仓库、*Coordinating、ErrorRouting 和 AppError 契约
Data 拥有 SwiftData/网络/同步/重试/后台 I/O 并实现领域层协议
读写流默认采用陈旧数据优先读取（stale-while-revalidate）和乐观排队写入
视图模型直接调用仓库协议（默认不使用用例/交互器层）

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

model-domain-mapping - 在领域层/数据层边界将 @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 - 对大型二进制数据使用外部存储

persist-repository-wrapper - 将 SwiftData 封装在领域层仓库协议之后
persist-model-macro - 对所有持久化类型应用 @Model 宏
persist-container-setup - 在应用级别配置 ModelContainer
persist-container-error-recovery - 处理 ModelContainer 创建失败并进行存储恢复
persist-context-environment - 通过 @Environment 访问 ModelContext（数据层）
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

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+）

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

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

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 自定义存储

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

🇺🇸English

SwiftData Best Practices — Modular MVVM-C Data Layer

Comprehensive data modeling, persistence, sync architecture, and error handling guide for SwiftData aligned with the clinic modular MVVM-C stack.

Architecture Alignment

This skill enforces the same modular architecture mandated by 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  │
└───────────────────────────────────────────────────────────────┘

Key principle: SwiftData types (@Model, ModelContext, @Query, FetchDescriptor) live in Data-only implementation code. Feature Views/ViewModels work with Domain types and protocol dependencies.

Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

Feature modules import Domain + DesignSystem only (never Data, never sibling features)
App target is the convergence point and owns DependencyContainer, concrete coordinators, and Route Shell wiring
Domain stays pure Swift and defines models plus repository, *Coordinating, ErrorRouting, and AppError contracts
Data owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
ViewModels call repository protocols directly (no default use-case/interactor layer)

When to Apply

Reference these guidelines when:

Defining @Model entity classes and mapping them to domain structs
Setting up ModelContainer and ModelContext in the Data layer
Implementing repository protocols backed by SwiftData
Writing stale-while-revalidate repository reads (AsyncStream)
Implementing optimistic writes plus queued sync operations
Configuring entity relationships (one-to-many, inverse)
Fetching from APIs and persisting to SwiftData via sync coordinators
Handling save failures, corrupt stores, and migration errors
Routing AppError traits to centralized error UI infrastructure
Building preview infrastructure with sample data
Planning schema migrations for app updates

Workflow

Use this workflow when designing or refactoring a SwiftData-backed feature:

Domain design: define domain structs (Trip, Friend) with validation/computed rules (see model-domain-mapping, state-business-logic-placement)
Entity design: define @Model entity classes with mapping methods (see model-*, model-domain-mapping)
Repository protocol: define in Domain layer, implement with SwiftData in Data layer (see persist-repository-wrapper)
Container wiring: configure ModelContainer once at the app boundary with error recovery (see persist-container-setup, )

Troubleshooting

Data not persisting -> persist-model-macro, persist-container-setup, persist-autosave, schema-configuration
List not updating after background import -> query-background-refresh, persist-model-actor
List not updating (same-context) -> query-property-wrapper, state-wrapper-views
Duplicates from API sync -> schema-unique-attributes, sync-conflict-resolution

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Data Modeling	CRITICAL	`model-`
2	Persistence Setup	CRITICAL	`persist-`
3	Querying & Filtering	HIGH	`query-`
4	CRUD Operations	HIGH	`crud-`
5	Sync & Networking

Quick Reference

1. Data Modeling (CRITICAL)

model-domain-mapping - Map @Model entities to domain structs across Domain/Data boundaries
model-custom-types - Use custom types over parallel arrays
model-class-for-persistence - Use classes for SwiftData entity types
model-identifiable - Conform entities to Identifiable with UUID
model-initializer - Provide custom initializers for entity classes
- Use computed properties for derived data

2. Persistence Setup (CRITICAL)

persist-repository-wrapper - Wrap SwiftData behind Domain repository protocols
persist-model-macro - Apply @Model macro to all persistent types
persist-container-setup - Configure ModelContainer at the App level
persist-container-error-recovery - Handle ModelContainer creation failure with store recovery
persist-context-environment - Access ModelContext via @Environment (Data layer)
- Enable autosave for manually created contexts

3. Querying & Filtering (HIGH)

query-property-wrapper - Use @Query for declarative data fetching (Data layer)
query-background-refresh - Force view refresh after background context inserts
query-sort-descriptors - Apply sort descriptors to @Query
query-predicates - Use #Predicate for type-safe filtering
query-dynamic-init - Use custom view initializers for dynamic queries
- Use FetchDescriptor outside SwiftUI views

4. CRUD Operations (HIGH)

crud-insert-context - Insert models via repository implementations
crud-delete-indexset - Delete via repository with IndexSet from onDelete
crud-sheet-creation - Use sheets for focused data creation via ViewModel
crud-cancel-delete - Avoid orphaned records by persisting only on save
crud-undo-cancel - Enable undo and use it to cancel edits
- Provide EditButton for list management

5. Sync & Networking (HIGH)

sync-fetch-persist - Use injected sync services to fetch and persist API data
sync-offline-first - Design offline-first architecture with repository reads and background sync
sync-conflict-resolution - Implement conflict resolution for bidirectional sync

6. Relationships (MEDIUM-HIGH)

rel-optional-single - Use optionals for optional relationships
rel-array-many - Use arrays for one-to-many relationships
rel-inverse-auto - Rely on SwiftData automatic inverse maintenance
rel-delete-rules - Configure cascade delete rules for owned relationships
rel-explicit-sort - Sort relationship arrays explicitly

7. SwiftUI State Flow (MEDIUM-HIGH)

state-query-vs-viewmodel - Route all data access through @Observable ViewModels
state-business-logic-placement - Place business logic in domain value types and repository-backed ViewModels
state-dependency-injection - Inject repository protocols via @Environment
state-bindable - Use @Bindable for two-way model binding
state-local-state - Use @State for view-local transient data
- Extract wrapper views for dynamic query state

8. Schema & Migration (MEDIUM-HIGH)

schema-define-all-types - Define schema with all model types
schema-unique-attributes - Use @Attribute(.unique) for natural keys
schema-unique-macro - Use #Unique for compound uniqueness (iOS 18+)
schema-index - Use #Index for hot predicates and sorts (iOS 18+)
schema-migration-plan - Plan migrations before changing models
- Plan migration recovery for schema changes

9. Sample Data & Previews (MEDIUM)

preview-sample-singleton - Create a SampleData singleton for previews
preview-in-memory - Use in-memory containers for preview isolation
preview-static-data - Define static sample data on model types
preview-main-actor - Annotate SampleData with @MainActor

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

Weekly Installs

Repository

pproenca/dot-skills

GitHub Stars

First Seen

Feb 10, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex56

github-copilot55

gemini-cli55

kimi-cli54

opencode54

amp53

SwiftData 最佳实践：模块化 MVVM-C 数据层架构、持久化与同步指南

🇨🇳中文介绍

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

架构对齐

相关 Skills

诊所架构契约 (iOS 26 / Swift 6.2)

适用场景

工作流程

故障排除

按优先级划分的规则类别

快速参考

1. 数据建模（关键）

2. 持久化设置（关键）

3. 查询与过滤（高）

4. CRUD 操作（高）

5. 同步与网络（高）

6. 关系（中高）

7. SwiftUI 状态流（中高）

8. 模式与迁移（中高）

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

使用方法

参考文件