第6章：Schema和版本迁移

轻量级迁移 (Lightweight Migration)

什么是轻量级迁移？

轻量级迁移是SwiftData提供的一种自动化数据模型迁移机制，适用于满足特定条件的模型变更。当开发者对@Model数据模型进行简单修改时（如添加新属性/关系、重命名字段等），系统可自动完成数据存储结构的转换，无需编写手动迁移代码。

支持的变更类型

以下变更类型支持轻量级迁移：

  1. 属性操作

    • 添加新属性（需设置默认值或标记为可选）
    • 删除现有属性
    • 修改属性类型（仅限兼容类型转换，如Int→Double）

  2. 关系操作

    • 添加/删除关系
    • 修改关系删除规则（如nullify→cascade）

  3. 模型操作

    • 添加/删除@Model类型
    • 重命名模型类（需配合versionedSchema声明）

实现步骤

1. 启用模型版本控制

// 定义版本化Schema
enum MyAppSchema: VersionedSchema {
    static var versionIdentifier = Schema.Version(1, 0, 0)
    static var models: [any PersistentModel.Type] = [
        TodoItem.self,  // v1.0模型
        Category.self
    ]
}

// 配置ModelContainer时指定版本
let container = try ModelContainer(
    for: MyAppSchema.self,
    configurations: ModelConfiguration()
)

2. 修改模型后更新版本号

enum MyAppSchema: VersionedSchema {
    static var versionIdentifier = Schema.Version(1, 1, 0) // 升级小版本
    static var models: [any PersistentModel.Type] = [
        TodoItem.self,  // 添加了新属性
        Category.self,
        Tag.self        // 新增模型
    ]
}

3. 配置轻量级迁移选项

let container = try ModelContainer(
    for: MyAppSchema.self,
    configurations: ModelConfiguration(
        isStoredInMemoryOnly: false,
        allowsSave: true,
        migrationPlan: MyMigrationPlan.self  // 可选的迁移计划
    )
)

注意事项

  1. 默认值处理
    新增非可选属性时，必须通过以下方式之一处理：

    @Attribute(.transformable(encoder: JSONEncoder(), decoder: JSONDecoder()))
var tags: [String] = []  // 直接默认值

@Attribute 
var priority: Int?       // 或设为可选

  2. 重命名操作
    需要显式声明原始名称：

    @Attribute(originalName: "oldName")
var newName: String

  3. 测试验证
    建议在开发阶段使用以下调试配置：

    ModelConfiguration(
    url: URL(filePath: "/dev/null")  // 内存存储
)

常见问题排查

问题现象可能原因解决方案
崩溃提示Can't resolve mapping model不支持的变更类型改用自定义迁移
数据丢失未设置合理的删除规则检查@Relationship的deleteRule
性能下降大数据量迁移分批次处理或后台迁移

最佳实践：始终在模拟器或测试设备上验证迁移结果，再发布到生产环境。

Last Updated::