swiftdata-expert-skill（Swiftdata 专家技能）

SwiftData Expert Skill

Overview

Use this skill to build, review, and harden SwiftData persistence architecture with Apple-documented patterns from iOS 17 through current updates. Prioritize data integrity, migration safety, sync correctness, and predictable concurrency behavior.

Agent Behavior Contract (Follow These Rules)

1. Identify the minimum deployment target before recommending APIs (notably #Index, #Unique, HistoryDescriptor, DataStore, inheritance examples).
2. Confirm the app has real ModelContainer wiring before debugging data issues; without it, inserts fail and fetches are empty.
3. Distinguish main-actor UI operations from background persistence operations; never assume one context fits both.
4. Treat schema changes as migration changes: evaluate lightweight migration first, then SchemaMigrationPlan when needed.
5. For CloudKit-enabled apps, verify schema compatibility constraints before proposing model changes.
6. Prefer deterministic query definitions (shared predicates, explicit sort order, bounded fetches) over ad hoc filtering in views.
7. Use persistent history tokens when reading cross-process changes; delete stale history to avoid storage growth.
8. In code reviews, prioritize data loss risk, accidental mass deletion, sync divergence, and context-isolation bugs over style changes.

Analysis Commands (Use Early)

• Search container setup:

- rg "modelContainer\\(|ModelContainer\\(" -n

• Search model definitions:

- rg "^@Model|#Unique|#Index|@Relationship|@Attribute|@Transient" -n

• Search context usage:

- rg "modelContext|mainContext|ModelContext\\(" -n

• Search migrations and history:

- rg "SchemaMigrationPlan|VersionedSchema|MigrationStage|fetchHistory|deleteHistory|historyToken" -n

• Search CloudKit and app groups:

- rg "cloudKitDatabase|iCloud|CloudKit|groupContainer|AppGroup|NSPersistentCloudKitContainer" -n

Project Intake (Before Advising)

• Determine deployment targets: iOS, iPadOS, macOS, watchOS, and visionOS.
• Locate container setup: .modelContainer(...) modifier or manual ModelContainer(...).
• Verify whether autosave is expected and whether explicit save() is required.
• Check if undo is enabled (isUndoEnabled) and whether operations occur on mainContext or custom contexts.
• Check CloudKit capabilities and chosen container strategy (automatic, .private(...), .none).
• Check if app group storage is required.
• Check if Core Data coexistence is in scope.
• Check if schema changes must be backward-compatible with existing user data.

Workflow Decision Tree

1. Need a new model or schema shape:

- Read references/modeling-and-schema.md.

1. Need create, update, delete behavior or context correctness:

- Read references/model-context-and-lifecycle.md.

1. Need filtering, sorting, or dynamic list behavior:

- Read references/querying-and-fetching.md.

1. Need relationship modeling or inheritance:

- Read references/relationships-and-inheritance.md.

1. Need migration planning, release upgrades, or change tracking:

- Read references/migrations-and-history.md.

1. Need iCloud sync or CloudKit compatibility:

- Read references/cloudkit-sync.md.

1. Need incremental migration from Core Data:

- Read references/core-data-adoption.md.

1. Need background isolation or actor-based persistence:

- Read references/concurrency-and-actors.md.

1. Need quick diagnostics or API availability checks:

- Read references/troubleshooting-and-updates.md.

1. Need end-to-end execution playbook for a concrete task:

• Read references/implementation-playbooks.md.

Triage-First Playbook (Common Problems -> Next Move)

• Insert fails or fetch is always empty:

- Confirm .modelContainer(...) is attached at app or window root and the model type is included.

• Duplicate rows appear after network refresh:

- Add @Attribute(.unique) or #Unique constraints and rely on insert-upsert behavior.

• Unexpected data loss during delete:

- Audit delete rules (.cascade vs .nullify) and check for unbounded delete(model:where:).

• Undo or redo does nothing:

- Ensure isUndoEnabled: true and that changes are saved via mainContext (not only background context).

• CloudKit sync not behaving:

- Check capabilities, remote notifications, and CloudKit schema compatibility; explicitly set cloudKitDatabase if multiple containers exist.

• Widget or App Intent changes are not reflected:

- Use persistent history (fetchHistory) with token + author filtering.

• historyTokenExpired appears:

- Reset local token strategy and rebootstrap change consumption from a safe point.

• Query results are expensive or unstable:

- Use shared predicate builders, explicit sorting, and bounded FetchDescriptor settings.

Anti-Patterns (Reject by Default)

• Building persistence logic before validating container wiring.
• Performing broad deletes without predicate review and confirmation.
• Mixing UI-driven editing and background write pipelines without isolation boundaries.
• Relying on ad hoc in-memory filtering instead of store-backed predicates.
• Enabling CloudKit sync without capability setup and schema compatibility checks.
• Shipping schema changes without migration rehearsal on existing user data.
• Consuming history without token persistence and cleanup policy.

Core Patterns

App-level container wiring (SwiftUI)

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            RootView()
        }
        .modelContainer(for: [Trip.self, Accommodation.self])
    }
}

Manual container configuration

let config = ModelConfiguration(isStoredInMemoryOnly: false)
let container = try ModelContainer(
    for: Trip.self,
    Accommodation.self,
    configurations: config
)

Dynamic query setup in a view initializer

struct TripListView: View {
    @Query private var trips: [Trip]

    init(searchText: String) {
        let predicate = #Predicate<Trip> {
            searchText.isEmpty || $0.name.localizedStandardContains(searchText)
        }
        _trips = Query(filter: predicate, sort: \.startDate, order: .forward)
    }

    var body: some View { List(trips) { Text($0.name) } }
}

Safe batch delete pattern

do {
    try modelContext.delete(
        model: Trip.self,
        where: #Predicate { $0.endDate < .now },
        includeSubclasses: true
    )
    try modelContext.save()
} catch {
    // Handle delete and save failures.
}

Reference Files

• references/modeling-and-schema.md
• references/model-context-and-lifecycle.md
• references/querying-and-fetching.md
• references/relationships-and-inheritance.md
• references/migrations-and-history.md
• references/cloudkit-sync.md
• references/core-data-adoption.md
• references/concurrency-and-actors.md
• references/troubleshooting-and-updates.md
• references/implementation-playbooks.md

Best Practices Summary

1. Keep model code as the source of truth; avoid hidden schema assumptions.
2. Apply explicit uniqueness and indexing strategy for large or frequently queried datasets.
3. Insert root models and let SwiftData traverse relationship graphs automatically.
4. Keep query behavior deterministic with explicit predicates and sort descriptors.
5. Bound fetches (fetchLimit, offsets, identifier-only fetches) for scalability.
6. Treat delete rules as business rules; review them during schema changes.
7. Use ModelConfiguration for environment-specific behavior (in-memory tests, CloudKit, app groups, read-only stores).
8. Handle history as an operational system: token persistence, filtering, and cleanup.
9. Use model actors or isolated contexts for non-UI persistence work.
10. Gate recommendations by API availability and deployment target.

Verification Checklist (After Changes)

• Build succeeds for target platforms and minimum deployment versions.
• CRUD tests pass with real store and in-memory store.
• Relationship deletes behave as intended (cascade, nullify, and others).
• Query behavior is stable with realistic datasets and sort or filter combinations.
• Migration path is validated on pre-existing data (not only clean installs).
• CloudKit behavior is validated in a development container before release.
• Cross-process changes (widgets, intents, extensions) are observed correctly.
• Error paths and rollback behavior are covered for destructive operations.

Response Contract

• For review tasks, report findings first by severity and include exact file paths and lines.
• For implementation tasks, describe:

- container or context changes, - schema or migration changes, - query or performance changes, - verification steps run and any gaps.

• If deployment target blocks a recommended API, provide the best fallback compatible with the current target.