Core Data 版本号迁移经验总结

大家在学习和使用Core Data过程中，第一次进行版本号迁移的经历一定是记忆犹新，至少我是这种，XD。弄的不好，就会搞出一些因为迁移过程中数据模型出错导致的Crash。这里总结了一下Core Data版本号迁移过程中的经验。希望对大家实用。

写在前面

关于Core Data版本号迁移，这两篇文章都进行了分析，大家能够參考。

• Core Data Model Versioning and Data Migration Programming Guide
• 自己定义 Core Data 迁移

迁移准备

1) 选中project中的 xcdaramodeId 文件，Menu->Editor->Add Model Version

这一步加入完毕之后。project中的*xcdaramodeId* 文件将会被展开，而且出现了新添加的Model文件

2) 在Xcode右側的辅助工具栏中找到 Model Version, 选择刚刚加入的Model文件，这个时候你会发现Xcode文件夹中。Model文件上的绿色的勾选中了当前选择的Model文件

3) 在新的Model文件里改动最新的Entities等信息，记得也同一时候改动NSManagedObject Subclass相应的实现

4) 改动 NSPersistentStoreCoordinator 部分实现:

let modelFilename = "the model file name in your project"
let modelPath = NSBundle.mainBundle().pathForResource(modelFIlename, ofType: "momd")

let managedObjectModel = NSManagedObjectModel(contentsOfURL: NSURL.fileURLWithPath(modelPath)

let persistentStoreCoordinator = NSPersistentStoreCoordinator(managedObjectModel: managedObjectModel)

// 这里是加入的部分。名如其意，当我们须要自己主动版本号迁移时，我们须要在addPersistentStoreWithType方法中设置例如以下options
let options = [NSInferMappingModelAutomaticallyOption: true, NSMigratePersistentStoresAutomaticallyOption: true] 

var error: NSError? = nil
persistentStoreCoordinator.addPersistentStoreWithType(NSSQLiteStoreType, configuration: nil, URL: storeURL, options: options, error: &error)

轻量级迁移

当我们不过对数据模型添加实体或者可选属性时。上述步骤完毕后执行代码进行迁移是奏效的。这个过程文档中叫做 Lightweight Migration 。当我们进行轻量级迁移时。 NSPersistentStoreCoordinator 会为我们自己主动判断出一个 Mapping Model 。假设有更加复杂的改变，我们就须要自己去实现Mapping Mode。

加入Mapping Model过程: New File->CoreData->Mapping Model, 选择我们须要进行Mapping的两个Model，终于会生成一个 *xcmappingmodel* 文件，大家能够打开文件，看到里面生成了Model之间的映射。

官方文档中介绍例如以下的改变支持轻量级迁移：

• 为Entity简单的加入一个属性
• 为Entity移除一个属性
• 属性值由 Optional<-> Non-optional 之间转换
• 为属性设置 Default Value
• 重命名Entity或者Attribute
• 添加一个新的relationship 或者删除一个已经存在的 relationship
• 重命名relationship
• 改变relationship to-one<-> to-many 等
• 添加。删除Entities
• 添加新的 Parent 或者 Child Entity
• 从Hierarchy中移除Entities

轻量级迁移不支持合并Entity的层级：比方在旧的Model中两个已知的Entities没有共享一个共同的Parent Entity，那么在新的Model中它们也不可以共享一个共同的Parent Entity。

在为属性或者Entity等重命名时，我们须要在Xcode右側辅助工具栏中找到 Versioning -&gt; RenamingID。设置Reanaming Identifier为之前相应的名称。

Mapping Models

假设我们对数据模型的改动不支持轻量级迁移，我们就须要像上文中所说的那样，自己创建Mapping Model。

打开创建好的 xcmappingmodel 文件，我们发现能够添加或者改动相应的 Entity Mappings, Attibute Mappings 和 Relationship Mappings。

Core Data提供了例如以下一组变量同意我们进行配置:

NSMigrationManagerKey: $manager

NSMigrationSourceObjectKey: $source

NSMigrationDestinationObjectKey: $destination

NSMigrationEntityMappingKey: $entityMapping

NSMigrationPropertyMappingKey: $propertyMapping

NSMigrationEntityPolicyKey: $entityPolicy

有时候，我们不只须要改动Entity的属性或者关系。能够使用NSEntityMigrationPolicy 自己定义整个迁移的过程。

继承NSEntityMigrationPolicy 实现迁移过程，然后选中相应的Entity Mapping，在Xcode右側辅助工具栏中找到Custom Policy，并设置为实现迁移相应的类名。

NSEntityMigrationPolicy

NSEntityMigrationPolicy眼下提供了7个方法可供实现。它们的调用顺序例如以下:

1) 当迁移将要開始时，会调用

func beginEntityMapping(mapping: NSEntityMapping, manager: NSMigrationManager, error: NSErrorPointer) -> Bool

2) 在旧数据上构建新的实例时调用

func createDestinationInstancesForSourceInstance(sInstance: NSManagedObject, entityMapping mapping: NSEntityMapping, manager: NSMigrationManager, error: NSErrorPointer) -> Bool

结束时调用

func endInstanceCreationForEntityMapping(mapping: NSEntityMapping, manager: NSMigrationManager, error: NSErrorPointer) -> Bool

3) 构建新的RelationShips调用

func createRelationshipsForDestinationInstance(dInstance: NSManagedObject, entityMapping mapping: NSEntityMapping, manager: NSMigrationManager, error: NSErrorPointer) -> Bool`

结束时调用

func endRelationshipCreationForEntityMapping(mapping: NSEntityMapping, manager: NSMigrationManager, error: NSErrorPointer) -> Bool

4) 验证，保存数据调用

func performCustomValidationForEntityMapping(mapping: NSEntityMapping, manager: NSMigrationManager, error: NSErrorPointer) -> Bool

5) 迁移结束时调用

func endEntityMapping(mapping: NSEntityMapping, manager: NSMigrationManager, error: NSErrorPointer) -> Bool

迁移过程

这里分享的是自己项目中数据自己定义迁移的整个过程。并附上部分代码实现逻辑。

项目中採用的是渐进式迁移，渐进式迁移的概念在 自己定义 Core Data 迁移 一文中有介绍：

// 这段文字取自 <<自己定义 Core Data 迁移>> 一文

想像一下你刚刚部署一个包括版本号 3 的数据模型的更新。你的某个用户已经有一段时间没有更新你的应用了。这个用户还在版本号 1 的数据模型上。
那么如今你就须要一个从版本号 1 到版本号 3 的映射模型。同一时候你也须要版本号 2 到版本号 3 的映射模型。当你加入了版本号 4 的数据模型后。那你就须要创建三个新的映射模型。显然这样做的扩展性非常差，那就来试试渐进式迁移吧。


与其为每一个之前的数据模型到最新的模型间都建立映射模型，还不如在每两个连续的数据模型之间创建映射模型。
曾经面的样例来说，版本号 1 和版本号 2 之间须要一个映射模型。版本号 2 和版本号 3 之间须要一个映射模型。
这样就能够从版本号 1 迁移到版本号 2 再迁移到版本号 3。显然，使用这样的迁移的方式时，若用户在较老的版本号上迁移过程就会比較慢。但它能节省开发时间并保证健壮性，由于你仅仅须要确保从之前一个模型到新模型的迁移工作正常就可以，而更前面的映射模型都已经经过了測试。

1) 推断本地SQLite数据库文件是否存在，不存在直接退出整个迁移。

2) 检測当前本地数据库和数据模型是否一致。假设一致就退出迁移。

let storeURL = NSURL(fileURLWithPath: "SQLite file path")
let managedObjectModel: NSManagedObjectModel  =  Your current managed object model

let sourceMetadata = NSPersistentStoreCoordinator.metadataForPersistentStoreOfType(NSSQLiteStoreType, URL:storeURL!, error: nil)

Bool needMigration = managedObjectModel.isConfiguration(nil, compatibleWithStoreMetadata: sourceMetadata)

3) 取得当前数据库存储时用的数据模型，假设获取不到或者获取失败。退出迁移。

 if let sourceModel = NSManagedObjectModel.mergedModelFromBundles(nil, forStoreMetadata: sourceMetadata!) {
    println("(sourceModel)")      
} else {
    return
}

4) 取得当前project中全部数据模型相应的managedObjectModel用于迁移，假设获取的结果少于两个就退出迁移。

5) 从全部的managedObjectModel中遍历出终于使用的Model和当前数据库採用的Model之间的全部Model。依照version顺序构建一个新的 Model list，确保第一个是sourceModel,最后一个是当前须要使用的managedObjectModel。

6) 对生成的这个Model list进行循环，開始渐进式迁移。

7) 构建Model list中相邻两个Model之间的NSMappingModel实例，用做迁移。

 for var index = 0; index < modelList.count - 1; index++ {
  let modelA = modelList[index]
  let modelB = modelList[index + 1]

  //检查是否有自己定义的Mapping model存在
  var mappingModel : NSMappingModel? = NSMappingModel(fromBundles: nil, forSourceModel: modelA, destinationModel: modelB)

  //假设不存在，尝试infer一个
    mappingModel = NSMappingModel.inferredMappingModelForSourceModel(modelA, destinationModel: modelB, error: nil)

    //假设终于取不到Mapping Model 就退出迁移
    //假设得到了Mapping Model，就能够開始进行迁移
}

8) 最终能够開始进行迁移了，XD

9) 创建一个新的文件路径用来存储迁移过程中的数据文件

10) 使用上文中的 modelA 和 modelB 构建一个 NSMigrationManager 实例，使用

func migrateStoreFromURL(sourceURL: NSURL, type sStoreType: String, options sOptions: [NSObject : AnyObject]?, withMappingModel mappings: NSMappingModel?, toDestinationURL dURL: NSURL, destinationType dStoreType: String, destinationOptions dOptions: [NSObject : AnyObject]?
, error: NSErrorPointer) -> Bool 

方法进行迁移，当中 toDestinationURL 參数是我们在步骤9中创建的路径。

假设migrate失败，就退出整个迁移过程。

11) 数据替换 1.把原始的source文件移动到新的backup目录中 2.使用步骤9中文件下生成的迁移之后的数据文件移动到原始的数据的路径下 3.删除backup

12) 回到步骤7，进行下一次迭代迁移。直到结束

迁移调试

我们能够在Xcode中设置启动參数 -com.apple.coredata.ubiquity.logLevel 3 或者 -com.apple.CoreData.SQLDebug 1 , 这样在程序执行时，控制台将会打印很多其它Core Data使用中的信息。包含调用的SQL语句。