引言：Core Data迁移的必要性

在Swift应用开发中，Core Data作为苹果官方推荐的数据持久化框架，其数据模型（.xcdatamodeld）的迭代升级是不可避免的。无论是添加新实体、修改属性类型，还是调整关系模型，任何数据模型的变更都需要通过迁移（Migration）机制确保现有数据的兼容性。默认的轻量级迁移（Lightweight Migration）虽能处理简单变更，但面对复杂场景（如属性拆分、实体合并）时，开发者必须掌握定制化迁移方案。本文将系统阐述Swift环境下Core Data迁移的核心原理、技术选型及实现细节。

一、Core Data迁移基础：版本与映射模型

1.1 数据模型版本管理

Core Data通过版本化数据模型（.xcdatamodeld文件中的版本）实现迁移。每次修改数据模型时，需创建新版本而非直接覆盖原文件：

// 在Xcode中右键.xcdatamodeld → "Show in Finder" → 复制并重命名版本文件夹

版本间的关联通过NSMappingModel（映射模型）定义，它描述了源模型到目标模型的字段映射规则。

1.2 轻量级迁移的适用场景

轻量级迁移自动处理以下变更：

• 添加/删除属性（非必需属性）
• 添加新实体
• 修改非关系型属性（如String→Int需谨慎）

启用方式（在NSPersistentStoreDescription中配置）：

let description = NSPersistentStoreDescription()
description.shouldMigrateStoreAutomatically = true
description.shouldInferMappingModelAutomatically = true

二、定制化迁移的三大场景与实现

2.1 场景1：属性类型变更与值转换

当修改属性类型（如Date→String）时，需通过NSEntityMigrationPolicy子类实现自定义转换：

class CustomMigrationPolicy: NSEntityMigrationPolicy {
    override func createDestinationInstances(forSource sourceInstance: NSManagedObject, 
                                           in mapping: NSEntityMapping, 
                                           manager: NSMigrationManager) throws {
        let destInstance = manager.createDestinationInstances(forEntityMapping: mapping, 
                                                             sourceInstances: [sourceInstance])
        guard let dest = destInstance.first else { return }
        // 示例：将Date转为ISO8601字符串
        if let sourceDate = sourceInstance.value(forKey: "timestamp") as? Date {
            dest.setValue(sourceDate.iso8601String, forKey: "timestampStr")
        }
    }
}

在映射模型中，需将对应属性的Value Expression设置为：

FUNCTION($manager, "destinationInstancesForSourceMappingNamed:entityMapping:manager:" , "CustomMapping", $entityMapping, $manager)

2.2 场景2：实体拆分与合并

合并两个实体（如LegacyUser→User+UserProfile）时，需分两步迁移：

1. 创建中间映射模型，将LegacyUser映射到User（保留核心字段）
2. 通过二次迁移将User的扩展字段映射到UserProfile

关键代码片段：

// 在迁移策略中处理关联关系
override func createRelationships(forDestination destinationInstance: NSManagedObject, 
                                in mapping: NSEntityMapping, 
                                manager: NSMigrationManager) throws {
    if let user = destinationInstance as? User {
        let profile = NSEntityDescription.insertNewObject(forEntityName: "UserProfile", 
                                                         into: manager.destinationContext)
        profile.setValue(user.value(forKey: "bio"), forKey: "biography")
        user.setValue(profile, forKey: "profile")
    }
}

2.3 场景3：数据清洗与转换

当需要修改数据格式（如统一电话号码格式）时，可在迁移过程中执行正则表达式处理：

override func createDestinationInstances(forSource sourceInstance: NSManagedObject, ...) throws {
    // ...获取源数据
    if var phone = sourceInstance.value(forKey: "phone") as? String {
        phone = phone.replacingOccurrences(of: "[^0-9]", with: "", options: .regularExpression)
        destInstance.setValue("+\(phone)", forKey: "normalizedPhone")
    }
}

三、重型迁移的完整实现流程

3.1 手动创建映射模型

1. 在Xcode中选择源数据模型版本 → Editor → Create Mapping Model
2. 手动配置每个实体的属性映射关系
3. 对复杂转换设置Custom Policy类

3.2 迁移管理器配置

func performHeavyMigration() throws {
    guard let sourceModel = NSManagedObjectModel(contentsOf: sourceModelURL),
          let destModel = NSManagedObjectModel(contentsOf: destModelURL) else {
        throw MigrationError.modelLoadFailed
    }
    let mappingModel = try NSMappingModel(from: [.init(bundle: Bundle.main)], 
                                          sourceModels: [sourceModel], 
                                          destinationModel: destModel)
    let migrationManager = NSMigrationManager(sourceModel: sourceModel, 
                                             destinationModel: destModel)
    migrationManager.mappingModel = mappingModel
    migrationManager.migrationPolicyClass = CustomMigrationPolicy.self // 可选
    try migrationManager.migrateStore(from: sourceStoreURL, 
                                     sourceType: NSSQLiteStoreType, 
                                     options: nil, 
                                     withMappingModel: mappingModel, 
                                     toDestinationURL: destStoreURL, 
                                     destinationType: NSSQLiteStoreType, 
                                     destinationOptions: nil)
}

3.3 性能优化技巧

• 分批处理：对大型数据集，通过NSBatchUpdateRequest分块迁移
• 异步执行：使用DispatchQueue.global().async避免阻塞主线程
• 进度监控：通过NSMigrationManager的migrationProgress属性实现进度条

四、测试与验证策略

4.1 单元测试覆盖

func testMigration() throws {
    let tempDir = FileManager.default.temporaryDirectory
    let sourceURL = tempDir.appendingPathComponent("source.sqlite")
    let destURL = tempDir.appendingPathComponent("dest.sqlite")
    // 1. 创建测试数据
    try createTestDatabase(at: sourceURL)
    // 2. 执行迁移
    try performHeavyMigration()
    // 3. 验证结果
    let context = NSManagedObjectContext(concurrencyType: .mainQueueConcurrencyType)
    let stack = CoreDataStack(modelName: "DestModel", storeURL: destURL)
    let request: NSFetchRequest<User> = User.fetchRequest()
    let count = try context.count(for: request)
    XCTAssertEqual(count, 100) // 验证记录数
}

4.2 边界条件测试

• 空数据库迁移
• 包含NULL值的字段迁移
• 超大二进制数据迁移
• 并发访问情况下的迁移

五、最佳实践与避坑指南

1. 版本控制：将数据模型文件纳入Git管理，每次变更提交详细说明
2. 渐进式迁移：复杂变更拆分为多个小版本迁移
3. 备份机制：迁移前自动备份原始数据库

   func backupDatabase(at sourceURL: URL) throws -> URL {
    let backupDir = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!
    let backupURL = backupDir.appendingPathComponent("backup_\(Date().timeIntervalSince1970).sqlite")
    try FileManager.default.copyItem(at: sourceURL, to: backupURL)
    return backupURL
   }

4. 错误处理：捕获并处理NSError的userInfo中的详细迁移错误
5. iOS版本兼容：测试不同iOS版本下的迁移行为差异

结论：定制迁移的核心价值

通过掌握Core Data定制迁移技术，开发者能够：

• 100%控制数据转换逻辑
• 处理轻量级迁移无法覆盖的复杂场景
• 确保数据完整性和应用稳定性
• 提升用户升级体验，避免数据丢失风险

建议开发者在项目初期即规划数据模型版本策略，并建立自动化迁移测试流程。对于历史遗留系统，可考虑编写迁移脚本生成工具，将重复性工作自动化。