一、Core Data 迁移的核心挑战与适用场景

Core Data 作为苹果生态的核心持久化框架，其模型迁移功能在应用迭代中至关重要。当数据模型（.xcdatamodeld）发生变更时，系统默认的自动迁移仅能处理简单场景（如新增属性、删除实体），而涉及数据类型转换、关系重构或复杂业务逻辑时，必须通过定制迁移实现。

典型迁移场景：

属性类型变更（String → Int）
实体拆分与合并
关系类型转换（To-One → To-Many）
数据清洗与规范化
历史数据迁移到新架构

二、迁移策略设计：轻量级 vs 重型迁移

1. 轻量级迁移（自动迁移）

适用于模型变更不破坏数据结构的情况，通过设置 NSMigrationManager 的 shouldMigrateStoreAutomatically 属性启用。

let modelURL = Bundle.main.url(forResource: "Model", withExtension: "momd")!
let managedObjectModel = NSManagedObjectModel(contentsOf: modelURL)!
let coordinator = NSPersistentStoreCoordinator(managedObjectModel: managedObjectModel)
let options = [
    NSMigratePersistentStoresAutomaticallyOption: true,
    NSInferMappingModelAutomaticallyOption: true
]
do {
    try coordinator.addPersistentStore(
        ofType: NSSQLiteStoreType,
        configurationName: nil,
        at: storeURL,
        options: options
    )
} catch {
    print("自动迁移失败: \(error)")
}

局限性：

无法处理数据类型转换
不支持复杂关系变更
无法执行自定义数据清洗逻辑

2. 重型迁移（定制迁移）

当模型变更超出自动迁移能力时，需通过 NSMappingModel 和 NSEntityMigrationPolicy 实现。

实施步骤：

创建新版数据模型
在 Xcode 中添加新模型版本（Editor → Add Model Version），确保继承链正确。
生成映射模型
手动创建 NSMappingModel 或通过 Xcode 的 “Create Mapping Model” 功能自动生成基础模板。
实现迁移策略
自定义 NSEntityMigrationPolicy 子类，重写关键方法：

class CustomMigrationPolicy: NSEntityMigrationPolicy {
    override func createDestinationInstances(
        forSourceInstance sourceInstance: NSManagedObject,
        in mapping: NSEntityMapping
    ) throws {
        // 创建目标实例
        let destinationInstance = NSEntityDescription.insertNewObject(
            forEntityName: mapping.destinationEntityName!,
            into: destinationContext!
        )
        // 属性映射与转换
        if let sourceValue = sourceInstance.value(forKey: "oldAttribute") as? String {
            let convertedValue = convertDataType(sourceValue)
            destinationInstance.setValue(convertedValue, forKey: "newAttribute")
        }
        // 关联关系处理
        if let relatedObject = sourceInstance.value(forKey: "relatedEntity") as? NSManagedObject {
            // 处理关系迁移逻辑
        }
    }
    private func convertDataType(_ input: String) -> Int {
        // 实现数据类型转换逻辑
        return Int(input) ?? 0
    }
}

三、高级迁移技术实践

1. 多步骤迁移（模型版本链）

当应用经历多次重大变更时，建议采用版本链式迁移：

ModelV1 → ModelV2 → ModelV3

实现要点：

每个版本间保持最小变更集
在 NSPersistentStoreCoordinator 中按顺序加载模型版本
为每对版本创建独立的映射模型

2. 批量数据迁移优化

对于大型数据集，需优化迁移性能：

override func createDestinationInstances(
    forSourceInstance sourceInstance: NSManagedObject,
    in mapping: NSEntityMapping
) throws {
    // 使用异步队列处理
    DispatchQueue.global(qos: .userInitiated).async {
        // 执行耗时操作
        DispatchQueue.main.async {
            // 更新UI或完成迁移
        }
    }
}

优化策略：

分批处理数据（每次迁移1000条）
使用临时内存存储减少I/O操作
监控内存使用，避免OOM

3. 迁移错误处理与回滚

实现健壮的错误处理机制：

enum MigrationError: Error {
    case dataConversionFailed
    case relationshipMappingError
    case unknownError(Error)
}
override func createDestinationInstances(...) throws {
    do {
        // 迁移逻辑
    } catch {
        if let conversionError = error as? DataConversionError {
            throw MigrationError.dataConversionFailed
        } else {
            throw MigrationError.unknownError(error)
        }
    }
}

回滚方案：

备份原始数据文件
实现迁移进度跟踪
提供手动回滚接口

四、测试与验证策略

1. 单元测试覆盖

为每个迁移策略编写测试用例：

func testAttributeConversion() {
    let policy = CustomMigrationPolicy()
    let sourceInstance = createTestSourceInstance()
    // 模拟迁移过程
    let destinationContext = NSManagedObjectContext(concurrencyType: .privateQueueConcurrencyType)
    // ... 设置测试环境
    try? policy.createDestinationInstances(
        forSourceInstance: sourceInstance,
        in: testMapping
    )
    // 验证结果
    let result = fetchMigratedData()
    XCTAssertEqual(result.newAttribute, expectedValue)
}

2. 集成测试场景

空数据库迁移测试
满数据量迁移测试（10万+记录）
跨版本链式迁移测试
异常中断恢复测试

五、最佳实践总结

版本控制规范
每次模型变更必须创建新版本，禁止直接修改当前模型
迁移策略复用
将通用转换逻辑封装为可复用组件（如日期格式转换器）
渐进式迁移
对于重大架构变更，考虑分阶段迁移：
- 第一阶段：添加兼容字段
- 第二阶段：迁移数据并弃用旧字段
- 第三阶段：清理废弃结构

监控与日志
实现迁移过程日志记录：

func logMigrationStep(_ step: String, status: String) {
    let logEntry = "\(Date()): \(step) - \(status)"
    // 写入文件或上传至监控系统
}

文档维护
为每个迁移版本维护变更说明文档，包含：
- 变更原因
- 影响范围
- 回滚方案
- 测试验证点

通过系统化的迁移策略设计和实现，开发者能够高效应对 Core Data 模型演进带来的挑战。实际项目中，建议结合 Xcode 的模型可视化工具与自定义迁移策略，在保证数据完整性的前提下实现平滑升级。对于超大规模数据集，可考虑结合后台服务进行离线迁移，进一步优化用户体验。

Swift 定制 Core Data 迁移：从基础到进阶的实现指南