MagicalRecord,一个简化CoreData操作的工具库

简介

• 项目主页: https://github.com/magicalpanda/MagicalRecord
• 实例下载: https://github.com/ios122/MagicalRecord

在软件工程中,活动记录模式是一种用于在关系数据库中存储数据的设计模式.这种设计模式最早由Martin Fowler在他的 Patterns of Enterprise Application Architecture 一书中命名.这样的一个对象的,接口应该包含插入,更新和删除的方法;再加上与底层数据库几乎直接对应的的属性.

MagicalRecord 受Ruby on Rails活动记录获取方式的便利性影响.项目目标是:

• 清理我的Core Data相关代码
• 支持清晰,简单,一行代码式的查询
• 当需要优化请求时,仍然可以修改 NSFetchRequest.

使用 CocoaPods 安装

1. 把下面一行添加到Podfile:

   pod "MagicalRecord"

2. 在工程目录执行:pod update(国内推荐使用pod update --verbose --no-repo-update)

3. 现在你可以添加#import <MagicalRecord/MagicalRecord.h>到任意项目源文件中,并开始使用MagicalRecord!

定义我们的数据模型

以定义实体 "Person"为例,它有属性age, firstname和lastname.

1. 创建一个新的数据模型,命名为TestModel(File --> New --> File-->Core Data > Data Model)
2. 添加一个新的实体,名为Person(Add Entity)
3. 添加属性age (Integer16), firstname (String)和 lastname (String)
   4.创建 NSManagedObject (Editor > Create NSManagedObject Subclass… > Create)子类以更好地管理我们的实体

Core Data的初始化与清理

如果在创建工程之初勾选了使用Core Data的选项,系统会自动在AppDelegate中生成大量的Core Data初始化与清理代码.但是那些完全各使用一行代码代替,如下:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions  {      [MagicalRecord setupCoreDataStack];      // ...      return YES;  }     - (void)applicationWillTerminate:(UIApplication *)application  {      [MagicalRecord cleanUp];  }

代码解读

首先,在需要使用MagicalRecord的地方,引入头文件:

#import <MagicalRecord/MagicalRecord.h>

然后,在你的App代理,- applicationDidFinishLaunching: withOptions:方法, 或-awakeFromNib方法中,使用下面方法中的 一种 来初始化 ** MagicalRecord** 类的调用:

+ (void)setupCoreDataStack;  + (void)setupAutoMigratingCoreDataStack;  + (void)setupCoreDataStackWithInMemoryStore;  + (void)setupCoreDataStackWithStoreNamed:(NSString *)storeName;  + (void)setupCoreDataStackWithAutoMigratingSqliteStoreNamed:(NSString *)storeName;  + (void)setupCoreDataStackWithStoreAtURL:(NSURL *)storeURL;  + (void)setupCoreDataStackWithAutoMigratingSqliteStoreAtURL:(NSURL *)storeURL;

每一个调用,实例化Core Data栈的某一个部分,并提供这些实例的获取器和设置器方法.这些实例在 MagicalRecord 中均可用,并被识别为 "默认实例".

如果工程有DEBUG标记,此时使用默认的SQLite数据存储,不创建新的版本的数据模型而是直接改变数据模型本身的方式,将会删除旧的存储并自动创建一个新的.这会节省大量的时间 - 不再需要在改变数据模型后每次都重新卸载和安装应用! 请确保发布应用时,不开启DEBUG标记: 不告知用户,直接删除应用的数据,真的很不好!

在你的应用退出前,你应该调用类方法+cleanUp:

[MagicalRecord cleanUp];

这用于使用MagicalRecord后的整理工作:解除我们自定义的错误处理器并把MagicalRecord创建的所有的Core Data 栈设为 nil.

开启iCloud 持久化存储

为了更好地使用苹果的iCloud Core Data 同步机制,使用下面初始化方法中的 一种 来替换来替换前面列出的标准初始化化方法:

+ (void)setupCoreDataStackWithiCloudContainer:(NSString *)containerID                                localStoreNamed:(NSString *)localStore;    + (void)setupCoreDataStackWithiCloudContainer:(NSString *)containerID                                 contentNameKey:(NSString *)contentNameKey                                localStoreNamed:(NSString *)localStoreName                        cloudStorePathComponent:(NSString *)pathSubcomponent;    + (void)setupCoreDataStackWithiCloudContainer:(NSString *)containerID                                 contentNameKey:(NSString *)contentNameKey                                localStoreNamed:(NSString *)localStoreName                        cloudStorePathComponent:(NSString *)pathSubcomponent                                     completion:(void (^)(void))completion;    + (void)setupCoreDataStackWithiCloudContainer:(NSString *)containerID                                localStoreAtURL:(NSURL *)storeURL;    + (void)setupCoreDataStackWithiCloudContainer:(NSString *)containerID                                 contentNameKey:(NSString *)contentNameKey                                localStoreAtURL:(NSURL *)storeURL                        cloudStorePathComponent:(NSString *)pathSubcomponent;    + (void)setupCoreDataStackWithiCloudContainer:(NSString *)containerID                                 contentNameKey:(NSString *)contentNameKey                                localStoreAtURL:(NSURL *)storeURL                        cloudStorePathComponent:(NSString *)pathSubcomponent                                     completion:(void (^)(void))completion;

更多细节,请阅读 Apple's "iCloud Programming Guide for Core Data" .

注意

如果你正在管理多重是用iCloud的数据存储,我们建议你使用那些更长的初始化方法,以自定义 contentNameKey .较短的初始化方法,会基于你应用的 bundle id(CFBundleIdentifier),自动生成 NSPersistentStoreUbiquitousContentNameKey .

操作被管理的对象上下文

对象上下文环境是你操作Core Data内数据的基础,只有正确获取到了上下文环境,才有可能进行相关的读写操作.换句话说,程序的任意位置,只要能正确获取上下文,都能进行Core Data的操作.这也是使用Core Data共享数据的基础之一.相较于传统的方式,各个页面之间只需要与一个透明的上下文环境进行交互,即可进行页面间数据的共享.

下面是一个简单的例子,具体含义下文都会提到:

// 获取上下文环境      NSManagedObjectContext *localContext    = [NSManagedObjectContext MR_context];            // 在当前上下文环境中创建一个新的 Person 对象.      Person *person  = [Person MR_createEntityInContext:localContext];      person.firstname = firstname;      person.lastname  = lastname;      person.age       = age;            // 保存修改到当前上下文中.      [localContext MR_saveToPersistentStoreAndWait];

创建新的对象上下文

许多简单的类方法可以用来帮助你创建一个新的对象上下文:

• + [NSManagedObjectContext MR_context]: 设置默认的上下文为它的父级上下文.并发类型为 NSPrivateQueueConcurrencyType .
• + [NSManagedObjectContext MR_newMainQueueContext]: 并发类型为 ** NSMainQueueConcurrencyType**.
• + [NSManagedObjectContext MR_newPrivateQueueContext]: 并发类型为 NSPrivateQueueConcurrencyType .
• + [NSManagedObjectContext MR_contextWithParent:…]: 允许自定义父级上下文.并发类型为 NSPrivateQueueConcurrencyType .
• + [NSManagedObjectContext MR_contextWithStoreCoordinator:…]:允许自定义持久化存储协调器.并发类型为 NSPrivateQueueConcurrencyType .

默认上下文

当使用Core Data时,你经常使用的连两类主要对象是:NSManagedObject和NSManagedObjectContext.

MagicalRecord 提供了一个简单类方法来获取一个默认的NSManagedObjectContext对象,这个对象在整个应用全局可用.这个上下文对象,在主线程操作,对于简单的单线程应用来说非常强大.

为了获取默认上下文,调用:

NSManagedObjectContext *defaultContext = [NSManagedObjectContext MR_defaultContext];

这个上下文对象,在MagicalRecord的任何需要使用上下文对象方法中都可以使用,但是并不需要给这些方法显示提供一个指定对象管理上下文对象参数.

如果你想创建一个新的对象管理上下文对象,以用于非主线程,可使用下面的方法:

NSManagedObjectContext *myNewContext = [NSManagedObjectContext MR_context];

这将会创建一个新的对象管理上下文,和默认的上下文对象有相同的对象模型和持久化存储;但是在另一个线程中使用时,是线程安全的.它自动设置默认上下文对象为父级上下文.

如果你想要将你的myNewContext实例作为所有获取请求默认的上下文对象,使用下面的类方法:

[NSManagedObjectContext MR_setDefaultContext:myNewContext];

在后台线程中执行任务

MagicalRecord 提供方法来设置和在后台线程中使用上下文对象.后台保存操作受UIView的动画回调方法启发,仅有的小小差别:

• 用于更改实体的block将永远不会在主线程执行.
• 在你的block内部提供一个单一的 NSManagedObjectContext 上下文对象.

例如,如果我们有一个Person实体对象,并且我们需要设置它的firstName和lastName字段,下面的代码展示了如何使用MagicalRecord来设置一个后台保存的上下文对象:

// 获取上下文环境 NSManagedObjectContext *defaultContext = [NSManagedObjectContext MR_defaultContext]; // 在当前上下文环境中创建一个新的 Person 对象. Person *person  = [Person MR_createEntityInContext:defaultContext];      person.firstname = @"firstname";      person.lastname  = @"lastname";      person.age       = @100; // 保存修改到当前上下文中. [defaultContext MR_saveToPersistentStoreAndWait];                  [MagicalRecord saveWithBlock:^(NSManagedObjectContext *localContext){                    Person *localPerson = [person MR_inContext:localContext];          localPerson.firstname = @"Yan";          localPerson.lastname = @"Feng";      }];

在这个方法中,指定的block给你提供了一个合适的上下文对象来执行你的操作,你不需要担心这个上下文对象的初始化来告诉默认上线文它准备好了,并且应当更新,因为变更是在另一个线程执行.

为了在保存block完成时执行某个操作,你可以使用 completion block:

// 获取上下文环境 NSManagedObjectContext *defaultContext = [NSManagedObjectContext MR_defaultContext]; // 在当前上下文环境中创建一个新的 Person 对象. Person *person  = [Person MR_createEntityInContext:defaultContext];      person.firstname = @"firstname";      person.lastname  = @"lastname";      person.age       = @100; // 保存修改到当前上下文中. [defaultContext MR_saveToPersistentStoreAndWait];                  [MagicalRecord saveWithBlock:^(NSManagedObjectContext *localContext){                    Person *localPerson = [person MR_inContext:localContext];          localPerson.firstname = @"Yan";          localPerson.lastname = @"Feng";      }  completion:^(BOOL success, NSError *error) {                    NSArray * persons = [Person MR_findAll];                    [persons enumerateObjectsUsingBlock:^(Person * obj, NSUInteger idx, BOOL * _Nonnull stop) {              NSLog(@"firstname: %@, lastname: %@\n", obj.firstname, obj.lastname);          }];                }];

这个完成的block,在主线程(队列)中调用,所以可以在此block里安全触发UI更新.

创建实体对象

为了创建并插入一个新的实体实例到默认上下文对象中,你可以使用:

Person *myPerson = [Person MR_createEntity];

创建实体实例,并插入到指定的上下文中:

Person *myPerson = [Person MR_createEntityInContext:otherContext];

删除实体对象

删除默认上下文中的实体对象:

[myPerson MR_deleteEntity];

删除指定上下文中的实体对象:

[myPerson MR_deleteEntityInContext:otherContext];

删除默认上下文中的所有实体:

[Person MR_truncateAll];

删除指定上下文中的所有实体:

[Person MR_truncateAllInContext:otherContext];

获取实体对象

基础查找

MagicalRecord中的大多数方法返回NSArray结果.

举个例子,如果你有一个名为 Person 的实体,和实体 Department 关联,你可以从持久化存储中获取所有的 Person 实体:

NSArray *people = [Person MR_findAll];

可以指定以某个属性排序:

NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName" ascending:YES];

可以使用多个属性进行排序:

NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName" ascending:YES];

当使用多个属性进行排序时,可以单独指定升序或降序.

NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName:NO,FirstName" ascending:YES]; // 或者 NSArray *peopleSorted = [Person MR_findAllSortedBy:@"LastName,FirstName:YES" ascending:NO];

如果你有办法通过某种方式从数据库中获取唯一的一个对象(比如,给对象一个特定的唯一标记),你可以使用下面方法获取某个实体对象:

Person *person = [Person MR_findFirstByAttribute:@"FirstName" withValue:@"Forrest"];

高级查找

如果查找条件很复杂,你可以使用正则表达式:

NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", @[dept1, dept2]];  NSArray *people = [Person MR_findAllWithPredicate:peopleFilter];

返回 一个 NSFetchRequest

NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];  NSFetchRequest *people = [Person MR_requestAllWithPredicate:peopleFilter];

每执行一次,就创建一个这些查询条件对应的NSFetchRequest和NSSortDescriptor.

自定义查询请求

NSPredicate *peopleFilter = [NSPredicate predicateWithFormat:@"Department IN %@", departments];    NSFetchRequest *peopleRequest = [Person MR_requestAllWithPredicate:peopleFilter];  [peopleRequest setReturnsDistinctResults:NO];  [peopleRequest setReturnPropertiesNamed:@[@"FirstName", @"LastName"]];    NSArray *people = [Person MR_executeFetchRequest:peopleRequest];

获取实体数量

你可以获取持久化存储中指定种类实体的总数量:

NSNumber *count = [Person MR_numberOfEntities];

或者,你也可以或者符合指定过滤条件的实体的总数量:

NSNumber *count = [Person MR_numberOfEntitiesWithPredicate:...];

有对应的返回NSUInteger的方法:

+ (NSUInteger) MR_countOfEntities;  + (NSUInteger) MR_countOfEntitiesWithContext:(NSManagedObjectContext *)context;  + (NSUInteger) MR_countOfEntitiesWithPredicate:(NSPredicate *)searchFilter;  + (NSUInteger) MR_countOfEntitiesWithPredicate:(NSPredicate *)searchFilter                                       inContext:(NSManagedObjectContext *)context;

集合操作

NSNumber *totalCalories = [CTFoodDiaryEntry MR_aggregateOperation:@"sum:" onAttribute:@"calories" withPredicate:predicate];    NSNumber *mostCalories  = [CTFoodDiaryEntry MR_aggregateOperation:@"max:" onAttribute:@"calories" withPredicate:predicate];    NSArray *caloriesByMonth = [CTFoodDiaryEntry MR_aggregateOperation:@"sum:" onAttribute:@"calories" withPredicate:predicate                                                             groupBy:@"month"];

在指定上下文中查找实体

所有的查找,获取和请求方法,都有一个对应的含有inContext:参数的方法,来让你指定要进行某种操作的具体上下文环境:

NSArray *peopleFromAnotherContext = [Person MR_findAllInContext:someOtherContext];    Person *personFromContext = [Person MR_findFirstByAttribute:@"lastName" withValue:@"Gump" inContext:someOtherContext];    NSUInteger count = [Person MR_numberOfEntitiesWithContext:someOtherContext];

保存实体对象

何时应该保存?

通常,你的应用应该在数据变化时,将其保存到持久化存储层中.有些应用选择仅在应用结束时保存,但是在大多数情况下并不需要这样做 - 实际上, 如果你仅在应用退出时保存数据,很有可能会丢失数据 !如果你的应用闪退了,会生什么?用户会丢失所有已经保存的数据 - 这是一种非常糟糕的用户体验,却又很容易避免.

如果你发现保存操作耗费了很长时间,你应该考虑使用一些方式优化:

1. 在后台线程保存: MagicalRecord 提供了一种简捷的API来改变并立即在后台线程保存数据 - 例如:

   [MagicalRecord saveWithBlock:^(NSManagedObjectContext *localContext) { // Do your work to be saved here, against the `localContext` instance // Everything you do in this block will occur on a background thread } completion:^(BOOL success, NSError *error) {      [application endBackgroundTask:bgTask];      bgTask = UIBackgroundTaskInvalid;  }];

2. 把任务分割成小块的保存任务: 某些数据量较大的任务,如导入大量的数据,应该被分割成更小块的保存任务.没有统一的标准规定单次保存多少任务最合适,所以你需要使用工具来测试你的应用工的性能以针对自己的应用进行调整.工具可选使用 Apple的 Instruments.

处理需要长时间运行的保存任务

当iOS应用退出时,有一个较短的时间来整理和保存数据到磁盘.如果你确定某个保存操作很可能会花费一定时间,最好的方式是请求延长应用的生命周期,比如这样:

UIApplication *application = [UIApplication sharedApplication];    __block UIBackgroundTaskIdentifier bgTask = [application beginBackgroundTaskWithExpirationHandler:^{      [application endBackgroundTask:bgTask];      bgTask = UIBackgroundTaskInvalid;  }];    [MagicalRecord saveWithBlock:^(NSManagedObjectContext *localContext) { // 这里有任何保存操作 } completion:^(BOOL success, NSError *error) {      [application endBackgroundTask:bgTask];      bgTask = UIBackgroundTaskInvalid;  }];

请确定已经仔细 阅读beginBackgroundTaskWithExpirationHandler相关文档 ,因为不适当或不必要地延长应用的生命周期,可能会导致应用被App Store拒绝.

导入数据

NSDictionary *contactInfo = // JSON解析器或其他数据源返回的结果. Person *importedPerson = [Person MR_importFromObject:contactInfo];

NSDictionary *contactInfo = // JSON解析器或其他数据源返回的结果. Person *person = [Person MR_createEntity]; // 这里不是必须为一个新创建的实体. [person MR_importValuesForKeysWithObject:contactInfo];

[MagicalRecord saveInBackgroundWithBlock:^(NSManagedObjectContext *)localContext {    Person *importedPerson = [Person MR_importFromObject:personRecord inContext:localContext];  }];

NSArray *arrayOfPeopleData = /// result from JSON parser NSArray *people = [Person MR_importFromArray:arrayOfPeopleData];

@interface MyGreatEntity    @property(readwrite, nonatomic, copy) NSString *identifier;    @end    @implementation MyGreatEntity    @dynamic identifier;    - (void)didImport:(id)data  {    if (NO == [data isKindOfClass:[NSDictionary class]]) {      return;    }      NSDictionary *dataDictionary = (NSDictionary *)data;      id identifierValue = dataDictionary[@"my_identifier"];      if ([identifierValue isKindOfClass:[NSNumber class]]) {      NSNumber *numberValue = (NSNumber *)identifierValue;        self.identifier = [numberValue stringValue];    }  }    @end

NSArray *arrayOfPeopleData = /// result from JSON parser NSArray *people = [Person MR_importFromArray:arrayOfPeopleData];  NSArray *idList = [arrayOfPeopleData valueForKey:@"id"];  NSPredicate *predicate = [NSPredicate predicateWithFormat:@"NOT(id IN %@)", idList];  [Person MR_deleteAllMatchingPredicate:predicate];

@implementation Person    -(void)willImport:(id)data {      NSArray *idList = [data[@"posts"] valueForKey:@"id"];      NSPredicate *predicate = [NSPredicate predicateWithFormat:@"NOT(id IN %@) AND person.id == %@", idList, self.id];      [Post MR_deleteAllMatchingPredicate:predicate];  }

// Objective-C #import <CocoaLumberjack/CocoaLumberjack.h> #import <MagicalRecord/MagicalRecord.h>

#define MR_LOGGING_DISABLED 1