一、Core Data 迁移基础与必要性

Core Data 作为苹果生态的核心持久化框架，其模型版本控制机制是应对数据结构变更的基础。当开发者修改实体属性、关系或新增实体时，旧版应用可能因模型不匹配而崩溃。Swift 项目中常见的迁移场景包括：

1. 属性类型变更（如 String 转 Int）
2. 实体关系重构（一对多转多对多）
3. 实体拆分与合并（用户信息拆分为基础信息/扩展信息）
4. 数据规范化处理（日期格式统一）

苹果提供的自动迁移（Lightweight Migration）虽能处理简单变更，但在复杂场景下（如跨版本数据转换、业务逻辑嵌入）必须采用定制化方案。例如某健康类应用在升级时需将历史体重数据从 kg 单位转换为 lb 单位，这要求在迁移过程中执行单位换算逻辑。

二、Swift 中的版本控制实现

1. 模型版本管理

通过 Xcode 的 Editor > Add Model Version 创建新版本时，需同步更新：

// AppDelegate.swift 配置示例
let container = NSPersistentContainer(name: "HealthData")
let description = NSPersistentStoreDescription()
description.migrationOptions = .migrateStoreOnMount // 启用迁移
container.persistentStoreDescriptions = [description]

2. 映射模型（Mapping Model）定制

对于复杂迁移，需创建 .xcmappingmodel 文件并手动配置：

• 实体映射（Entity Mapping）
• 属性映射（Property Mapping）
• 值转换器（Value Transformer）

示例：将旧版 User 实体的 fullName 拆分为新版的 firstName 和 lastName：

<!-- MappingModel.xcmappingmodel 片段 -->
<entityMapping entityName="User" sourceEntityName="LegacyUser">
    <propertyMapping source="fullName" destination="firstName" 
        valueTransformerName="FirstNameExtractor"/>
    <propertyMapping source="fullName" destination="lastName" 
        valueTransformerName="LastNameExtractor"/>
</entityMapping>

三、高级迁移策略实现

1. 手动迁移控制器

当自动迁移无法满足需求时，需实现 NSMigrationManager 子类：

class CustomMigrationManager: NSMigrationManager {
    override func migrateStoreFromURL(_ sourceURL: URL, 
                                    type: String, 
                                    options: [AnyHashable : Any] = [:], 
                                    withMappingModel mappingModel: NSMappingModel, 
                                    toDestinationURL destinationURL: URL, 
                                    destinationType: String, 
                                    destinationOptions: [AnyHashable : Any] = [:], 
                                    error error: NSErrorPointer) -> Bool {
        // 1. 执行基础迁移
        let success = super.migrateStoreFromURL(sourceURL, 
                                               type: type, 
                                               options: options, 
                                               withMappingModel: mappingModel, 
                                               toDestinationURL: destinationURL, 
                                               destinationType: destinationType, 
                                               destinationOptions: destinationOptions, 
                                               error: error)
        // 2. 执行自定义数据转换
        if success {
            performPostMigrationTransformations(at: destinationURL)
        }
        return success
    }
    private func performPostMigrationTransformations(at storeURL: URL) {
        // 实现数据清洗逻辑
    }
}

2. 渐进式迁移方案

对于百万级数据量的应用，建议采用分阶段迁移：

1. 版本1.0 → 1.1：结构调整（自动迁移）
2. 版本1.1 → 1.2：数据转换（手动迁移）
3. 版本1.2 → 2.0：UI适配

示例分阶段实现：

func performStagedMigration() {
    let storeURL = NSPersistentContainer.defaultDirectoryURL().appendingPathComponent("Model.sqlite")
    // 第一阶段：结构迁移
    if needsStructuralMigration(storeURL) {
        migrateStructurally(storeURL)
    }
    // 第二阶段：数据转换
    if needsDataTransformation(storeURL) {
        transformData(storeURL)
    }
}

四、数据完整性保障措施

1. 迁移前验证

func verifyStoreIntegrity(at url: URL) -> Bool {
    do {
        let coordinator = NSPersistentStoreCoordinator(managedObjectModel: managedObjectModel)
        try coordinator.addPersistentStore(ofType: NSSQLiteStoreType, 
                                          configurationName: nil, 
                                          at: url, 
                                          options: nil)
        return true
    } catch {
        print("Store verification failed: \(error)")
        return false
    }
}

2. 迁移回滚机制

class MigrationRollbackManager {
    private let backupURL: URL
    private let originalURL: URL
    init(originalStore: URL, backupDirectory: URL) {
        self.originalURL = originalStore
        self.backupURL = backupDirectory.appendingPathComponent("backup_\(Date().timeIntervalSince1970).sqlite")
    }
    func createBackup() throws {
        try FileManager.default.copyItem(at: originalURL, to: backupURL)
    }
    func restoreFromBackup() throws {
        try FileManager.default.removeItem(at: originalURL)
        try FileManager.default.copyItem(at: backupURL, to: originalURL)
    }
}

五、性能优化实践

1. 批量处理策略

对于大型数据集，建议采用分块处理：

func processEntitiesInBatches(context: NSManagedObjectContext, 
                             entityName: String, 
                             batchSize: Int = 500, 
                             processor: (NSManagedObject) -> Void) {
    let request = NSFetchRequest<NSFetchRequestResult>(entityName: entityName)
    request.fetchBatchSize = batchSize
    context.perform {
        do {
            let results = try context.fetch(request)
            for object in results {
                guard let managedObject = object as? NSManagedObject else { continue }
                processor(managedObject)
            }
        } catch {
            print("Batch processing failed: \(error)")
        }
    }
}

2. 异步迁移架构

class AsyncMigrationManager {
    private let backgroundQueue = DispatchQueue(label: "com.example.migrationQueue", 
                                              qos: .utility, 
                                              attributes: .concurrent)
    func startMigration(completion: @escaping (Bool, Error?) -> Void) {
        backgroundQueue.async {
            // 执行迁移逻辑
            let success = self.performMigration()
            DispatchQueue.main.async {
                completion(success, nil)
            }
        }
    }
    private func performMigration() -> Bool {
        // 具体迁移实现
        return true
    }
}

六、测试与验证体系

1. 单元测试用例

class CoreDataMigrationTests: XCTestCase {
    var persistentContainer: NSPersistentContainer!
    override func setUp() {
        super.setUp()
        persistentContainer = NSPersistentContainer(name: "TestModel")
        persistentContainer.persistentStoreDescriptions.first?.url = URL(fileURLWithPath: "/dev/null")
        persistentContainer.loadPersistentStores { _, error in
            if let error = error {
                XCTFail("Failed to load store: \(error)")
            }
        }
    }
    func testAttributeMigration() {
        let context = persistentContainer.viewContext
        // 创建测试数据
        // 执行迁移
        // 验证结果
    }
}

2. 集成测试方案

1. 创建测试数据库快照
2. 执行迁移流程
3. 验证数据一致性：
   • 记录计数验证
   • 关键字段值验证
   • 关系完整性验证

七、最佳实践总结

1. 版本控制原则：每个发布版本对应独立模型版本
2. 渐进式迁移：复杂迁移拆分为多个简单步骤
3. 数据备份：迁移前创建可恢复的备份
4. 性能监控：关键操作添加时间统计
5. 用户通知：长时间迁移时显示进度

示例进度监控实现：

protocol MigrationProgressDelegate: AnyObject {
    func migrationProgressUpdated(_ progress: Double)
    func migrationCompleted(_ success: Bool)
}
class ProgressAwareMigrationManager {
    weak var delegate: MigrationProgressDelegate?
    func performMigration() {
        // 模拟分步操作
        for step in 1...10 {
            let progress = Double(step) / 10.0
            delegate?.migrationProgressUpdated(progress)
            Thread.sleep(forTimeInterval: 0.5) // 模拟耗时操作
        }
        delegate?.migrationCompleted(true)
    }
}

通过系统化的迁移策略和严格的验证机制，开发者可以确保 Core Data 模型升级过程中的数据完整性和应用稳定性。实际项目中，建议结合具体业务需求选择适当的迁移方案，并在发布前进行充分的测试验证。