本文翻译自Simplifying RESTful API Use and Data Persistence on iOS with Mantle and Realm
iOS开发者都会熟悉Core Data,苹果的一种图形化对象的存储框架.除了本地存储外,它还有许多高级特性,比如对象的追踪和撤销.这些特性在某些情形非常有用,但学习起来并不那么容易,需要写大量的代码,学习曲线很陡.
2014年,Realm作为专为移动开发所设计的数据库,一经发布就引起开发界的注意.如果仅作为本地存储,Realm是很好的选择.毕竟并不是所有人都会用到Core Data的高级特性.Realm相当好用,且与CoreData不同的是它仅需要极少的代码.而且它是线程安全的,据说要快于苹果的存储框架.
在大多数的app中,数据存储占据重要的位置.我们经常要从远程服务器中通过RESTful API来解析数据,此时需要用到Mantle,它是用于Cocoa和Cocoa Touch模型转换的开源库.Mantle可以很轻松地完成JSON接口的模型转换工作.
本文我们将用纽约时报的搜索API来创建一个文章列表的应用.用的是标准的HTTP GET请求,接收和请求的模型用的是Mantle.我们将看到用Mantle来处理相应的值转换(例如NSDate到string)是多么方便.接收数据后,我们用Realm来存储它们.很少的代码即可完成以上操作.
- 开始RESTful API
我们先来创建一个”Master-Detail Application”的iOS项目,名字为“RealmMantleTurorial”.用CocoaPods来管理依赖库.Podfile文件需要以下内容:
pod 'Mantle'
pod 'Realm'
pod 'AFNetworking'
pods安装完成后,打开新创建的MantleRealmTutorialworkspace.你会发现,著名的网络库AFNetworking也已经安装好了.我们将用它来做API请求.
正如前文所说,纽约时报为我们提供了相当好用的文章搜索API.我们需要申请一个access key来使用它.去这里 完成此操作.当我们申请完API key时,就可以开始编码工作了.
在创建Mantle数据模型之前,需要完成网络层的操作.创建一个名为Network的group.在此group中我们将创建两个类.一个是AFHTTPSessionManager的子类,叫做SessionManager,它是AFNetworking中的一个session manager类,一个非常好用的网络库.SessionManager类将用单例来处理API的请求.我们创建后,拷贝下面的代码到相应地接口和实现代码中.
#import "AFHTTPSessionManager.h"
@interface SessionManager : AFHTTPSessionManager
+ (id)sharedManager;
@end
#import "SessionManager.h"
static NSString *const kBaseURL = @"http://api.nytimes.com";
@implementation SessionManager
- (id)init {
self = [super initWithBaseURL:[NSURL URLWithString:kBaseURL]];
if(!self) return nil;
self.responseSerializer = [AFJSONResponseSerializer serializer];
self.requestSerializer = [AFJSONRequestSerializer serializer];
return self;
}
+ (id)sharedManager {
static SessionManager *_sessionManager = nil;
static dispatch_once_t onceToken;
dispatch_once(&onceToken, ^{
_sessionManager = [[self alloc] init];
});
return _sessionManager;
}
@end
Session manager初始化了一个静态变量kBaseURL作为我们的基础URL.将用JSON格式的数据作为请求和接收的数据格式类型.
- 纽约时报搜索文章API预览
官方文档在这里,我们将用到以下接口:
http://api.nytimes.com/svc/search/v2/articlesearch
...解析这些文章需要一个日期范围的搜索查询.例如,我们要查询2015年7月第一周纽约时报中有关篮球的文章.根据接口文档,我们需要以下参数:
| Parameter | Value |
| -------------- |:--------------- :|
| q | "basketBall" |
| begin_date | "20150701" |
| begin_date | "20150707" |
返回的数据稍微有些复杂.下面是返回的数据中的其中一篇文章的数据(docs array中的一个元素)
{
"response": {
"docs": [
{
"web_url": "http://www.nytimes.com/2015/07/04/sports/basketball/robin-lopez-and-knicks-are-close-to-a-deal.html",
"lead_paragraph": "Lopez, a 7-foot center, joined Arron Afflalo, a 6-foot-5 guard, as the Knicks’ key acquisitions in free agency. He is expected to solidify the Knicks’ interior defense.",
"abstract": null,
"print_page": "1",
"source": "The New York Times",
"pub_date": "2015-07-04T00:00:00Z",
"document_type": "article",
"news_desk": "Sports",
"section_name": "Sports",
"subsection_name": "Pro Basketball",
"type_of_material": "News",
"_id": "5596e7ac38f0d84c0655cb28",
"word_count": "879"
}
]
},
"status": "OK",
"copyright": "Copyright (c) 2013 The New York Times Company. All Rights Reserved."
}
返回的数据中分为三个部分.第一部分response是docs数组的包含文章的内容.其他两部分是状态和版权信息.API已经请求完成,现在需要用Mantle来创建数据模型了.
-
Mantle介绍
如前文所述,Mantle是简化数据模型转换的开源库.我们先来创建一个文章列表的请求模型.我们命名这个类为ArticleListRequestModel,它是MTLModel的子类，所有Mantle模型都继承此类.另外我们需要它遵从MTLJSONSerializing协议.我们的请求模型里有三个请求参数,分别为query,articlesFromDate和articlesToDate.确保这个类在Models group里面.Mantle能简化数据模型,减少代码量
这里是ArticleListRequestModel接口中的内容:
#import "MTLModel.h"
#import "Mantle.h"
@interface ArticleListRequestModel : MTLModel <MTLJSONSerializing>
@property (nonatomic, copy) NSString *query;
@property (nonatomic, copy) NSDate *articlesFromDate;
@property (nonatomic, copy) NSDate *articlesToDate;
@end
如果你查看我们的请求参数与docs的请求参数,会发现API中的请求参数名和我们模型中的名字有所不同.Mantle用以下方法来解决:
+ (NSDictionary *)JSONKeyPathsByPropertyKey.
下面是请求模型文件的实现代码中需要做的:
#import "ArticleListRequestModel.h"
@implementation ArticleListRequestModel
#pragma mark - Mantle JSONKeyPathsByPropertyKey
+ (NSDictionary *)JSONKeyPathsByPropertyKey {
return @{
@"query": @"q",
@"articlesFromDate": @"begin_date",
@"articlesToDate": @"end_date"
};
}
@end
这个实现方法实现了将JSON数据转换为模型属性.一旦JSONKeyPathByPropertyKey方法实现,偶们就能用类方法+[MTLJSONAdapter JSONArrayForModels]将模型转为JSON词典.
有件事需要注意的是我们参数列表中的日期参数需要是"YYYYMMDD"格式.用Mantle很容易做到.我们需要增加一个自定义的属性值转换可选方法'+<propertyName>JSONTransformer'.通过这个方法来告诉Mantle在解析JSON数据的时候需要单独做出一些转变方法.我们也会实现反转方法用于创建模型转JSON的方法中.如果我们要将NSDate对象转为String,则需要用到NSDataFormatter类.下面是ArtcleListRequestModel类的实现代码:
#import "ArticleListRequestModel.h"
@implementation ArticleListRequestModel
+ (NSDateFormatter *)dateFormatter {
NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
dateFormatter.dateFormat = @"yyyyMMdd";
return dateFormatter;
}
#pragma mark - Mantle JSONKeyPathsByPropertyKey
+ (NSDictionary *)JSONKeyPathsByPropertyKey {
return @{
@"query": @"q",
@"articlesFromDate": @"begin_date",
@"articlesToDate": @"end_date"
};
}
#pragma mark - JSON Transformers
+ (NSValueTransformer *)articlesToDateJSONTransformer {
return [MTLValueTransformer transformerUsingForwardBlock:^id(NSString *dateString, BOOL *success,
NSError *__autoreleasing *error) {
return [self.dateFormatter dateFromString:dateString];
} reverseBlock:^id(NSDate *date, BOOL *success, NSError *__autoreleasing *error) {
return [self.dateFormatter stringFromDate:date];
}];
}
+ (NSValueTransformer *)articlesFromDateJSONTransformer {
return [MTLValueTransformer transformerUsingForwardBlock:^id(NSString *dateString, BOOL *success,
NSError *__autoreleasing *error) {
return [self.dateFormatter dateFromString:dateString];
} reverseBlock:^id(NSDate *date, BOOL *success, NSError *__autoreleasing *error) {
return [self.dateFormatter stringFromDate:date];
}];
}
@end
Mantle另一个非常棒的特性是这些模型全部遵从NSCoding协议,和实现isEqual和hash方法.
我们可以看到API返回的JSON数据包含了一个文章对象的数组.如果我们想要用Mantle来模型化这个返回值,需要创建独立的两个models.一个用来模型化文章集的对象(docs数组中的元素),另一个用来模型化整个JSON返回对象中包含docs数组的部分.现在,我们无需解析从接收的JSON数据到我们数据模型中的每个嵌套元素.假若我们只对文章对象的两部分lead_paragraph和web_url感兴趣.ArticleModel类很简单的就能实现,代码如下:
#import "MTLModel.h"
#import <Mantle/Mantle.h>
@interface ArticleModel : MTLModel <MTLJSONSerializing>
@property (nonatomic, copy) NSString *leadParagraph;
@property (nonatomic, copy) NSString *url;
@end
#import "ArticleModel.h"
@implementation ArticleModel
#pragma mark - Mantle JSONKeyPathsByPropertyKey
+ (NSDictionary *)JSONKeyPathsByPropertyKey {
return @{
@"leadParagraph": @"lead_paragraph",
@"url": @"web_url"
};
}
@end
现在文章的model已经被定义,我们能够实现对返回模型中文章列表对象的模型化.下面是ArticleList返回模型的代码:
#import "MTLModel.h"
#import <Mantle/Mantle.h>
#import "ArticleModel.h"
@interface ArticleListResponseModel : MTLModel <MTLJSONSerializing>
@property (nonatomic, copy) NSArray *articles;
@property (nonatomic, copy) NSString *status;
@end
#import "ArticleListResponseModel.h"
@class ArticleModel;
@implementation ArticleListResponseModel
#pragma mark - Mantle JSONKeyPathsByPropertyKey
+ (NSDictionary *)JSONKeyPathsByPropertyKey {
return @{
@"articles" : @"response.docs",
@"status" : @"status"
};
}
#pragma mark - JSON Transformer
+ (NSValueTransformer *)articlesJSONTransformer {
return [MTLJSONAdapter arrayTransformerWithModelClass:ArticleModel.class];
}
@end
这个类只有两个属性:status和articles.如果我们同endpoint的返回值来比较,就会发现第三个JSON属性版权没有转换到返回值模型中.在articlesJSONTransformer方法中,我们会看到它返回的是ArticleModel类的数组.
值得注意的是在JSONKeyPathsByPropertyKey方法里,模型属性文章集相当于JSON属性response里的docs数组.
截止现在,我们实现了三个model类:ArticleListRequestModel,ArticleModel,和ArticleLsitResponseModel.
- 第一个API请求
我们实现了所有数据模型,现在该返回APIManager类来用GET方法实现API请求.方法为:
- (NSURLSessionDataTask *) getArticlesWithRequestModel:(ArticleListRequestModel *)requestModel success:(void (^)(ArticleListResponseModel *responseModel))success failure:(void (^)(NSError *error))failure
ArticleListRequestModel请求模型作为参数,ArticleListResponseModel模型作为返回成功后的结果,不成功时返回一个NSError信息.我们使用AFNetworking来实现API的GET请求方法.请确保你已经有了前文所说的api access key,在这里获取.
#import "SessionManager.h"
#import "ArticleListRequestModel.h"
#import "ArticleListResponseModel.h"
@interface APIManager : SessionManager
- (NSURLSessionDataTask *)getArticlesWithRequestModel:(ArticleListRequestModel *)requestModel success:(void (^)(ArticleListResponseModel *responseModel))success failure:(void (^)(NSError *error))failure;
@end
#import "APIManager.h"
#import "Mantle.h"
static NSString *const kArticlesListPath = @"/svc/search/v2/articlesearch.json";
static NSString *const kApiKey = @"replace this with your own key";
@implementation APIManager
- (NSURLSessionDataTask *)getArticlesWithRequestModel:(ArticleListRequestModel *)requestModel
success:(void (^)(ArticleListResponseModel *responseModel))success
failure:(void (^)(NSError *error))failure{
NSDictionary *parameters = [MTLJSONAdapter JSONDictionaryFromModel:requestModel error:nil];
NSMutableDictionary *parametersWithKey = [[NSMutableDictionary alloc] initWithDictionary:parameters];
[parametersWithKey setObject:kApiKey forKey:@"api-key"];
return [self GET:kArticlesListPath parameters:parametersWithKey
success:^(NSURLSessionDataTask *task, id responseObject) {
NSDictionary *responseDictionary = (NSDictionary *)responseObject;
NSError *error;
ArticleListResponseModel *list = [MTLJSONAdapter modelOfClass:ArticleListResponseModel.class
fromJSONDictionary:responseDictionary error:&error];
success(list);
} failure:^(NSURLSessionDataTask *task, NSError *error) {
failure(error);
}];
}
有两件重要的事情在这个方法里,首先我们来看这行代码:
NSDictionary *parameters = [MTLJSONAdapter JSONDictionaryFromModel:requestModel error:nil];
这行代码利用MTLJSONAdapater类中提供的方法来获取一个从我们数据模型中转换来的NSDictionary.它将随JSON一起发送给API.这就是Mantle干的漂亮的地方.仅用一行代码就实现了ArticleListRequestModel类中的JSONKeyPathsByPropertyKey和+<propertyName>JSONTransformer方法,获取了我们数据模型所需的JSON数据.
Mantle还可以允许我们用同样方法来解析从API获得的数据.将获取的数据词典转换为ArticleListResponseModel类只需下面的方法:
ArticleListResponseModel *list = [MTLJSONAdapter modelOfClass:ArticleListResponseModel.class fromJSONDictionary:responseDictionary error:&error];
- 用Realm来存储数据
现在我们已经可以从远程API来解析数据,是时候来存储它们了.如前文所述,我们将用到Realm.Realm是用来替代Core Data和SQLite的移动数据库.正如下面所述,它非常易用:
Realm, the ultimate mobile database, is a perfect replacement for Core Data and SQLite.
用Realm来存储数据之前,我们需要创建一个RLMObject类的子类.创建一个存储单篇文章的模型类.代码如下,相当简单:
#import "RLMObject.h"
@interface ArticleRealm : RLMObject
@property NSString *leadParagraph;
@property NSString *url;
@end
这个是存储的基础,而类的实现代码为空.确保你写的model类中的属性没有其他例如nonatomic、Strong或者copy的描述.Realm会自动完成,无需我们关心.
我们得到的文章集利用Mantle转换为Article模型后,需要初始化ArticleRealm对象中的文章类.为了做到这些,需要在Realm模型中增加initWithMantleModel方法.下面是ArticleRealm类的实现代码:
#import "RLMObject.h"
#import "ArticleModel.h"
@interface ArticleRealm : RLMObject
@property NSString *leadParagraph;
@property NSString *url;
- (id)initWithMantleModel:(ArticleModel *)articleModel;
@end
#import "ArticleRealm.h"
@implementation ArticleRealm
- (id)initWithMantleModel:(ArticleModel *)articleModel{
self = [super init];
if(!self) return nil;
self.leadParagraph = articleModel.leadParagraph;
self.url = articleModel.url;
return self;
}
@end
我们用RLMRealm类来进行数据库中的数据交互.我们通过"[RLMRealm defaultRealm]"很容易就能得到一个RLMRealm对象.这个对象是线程安全的.往Realm写入数据相当简单明了.一次写入或者一系列的写入需要一个写入转换操作.下面是写入操作的例子:
RLMRealm *realm = [RLMRealm defaultRealm];
ArticleRealm *articleRealm = [ArticleRealm new];
articleRealm.leadParagraph = @"abc";
articleRealm.url = @"sampleUrl";
[realm beginWriteTransaction];
[realm addObject:articleRealm];
[realm commitWriteTransaction];
以上操作包含如下步骤:首先创建一个RLMRealm对象来与数据库交互.然后创建一个ArticleRealm模型对象(确保它是RLMRealm的子类).最后存储它,进行一个写入操作,这个对象被添加到数据库,完成存储后写入操作结束.我们可以看到写入操作会阻塞相应的线程.虽然Realm很快,但是如果我们在主线程中做很多的写入数据操作,UI就会被挂起,直到写入操作结束.一个好的解决办法就是将写入操作放在子线程中完成.
- Realm中的API 请求和对返回数据的存储
接下来我们利用Realm来存储文章集的所有信息.首先用下列方法来做一个API请求:
- (NSURLSessionDataTask *) getArticlesWithRequestModel:(ArticleListRequestModel *)requestModel success:(void (^)(ArticleListResponseModel *responseModel))success failure:(void (^)(NSError *error))failure
Mantle获取纽约时报发表于2015年7月头一周关于篮球文章集的请求和返回数据模型还没没有用到.一旦有文章获取时,我们便将它们存储在Realm里.下面的代码做的就是这些工作.在我们的app table view controller类的viewDidLoad方法里编写如下代码:
ArticleListRequestModel *requestModel = [ArticleListRequestModel new]; // (1)
requestModel.query = @"Basketball";
requestModel.articlesToDate = [[ArticleListRequestModel dateFormatter] dateFromString:@"20150706"];
requestModel.articlesFromDate = [[ArticleListRequestModel dateFormatter] dateFromString:@"20150701"];
[[APIManager sharedManager] getArticlesWithRequestModel:requestModel // (2)
success:^(ArticleListResponseModel *responseModel){
dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{ // (3)
@autoreleasepool {
RLMRealm *realm = [RLMRealm defaultRealm];
[realm beginWriteTransaction];
[realm deleteAllObjects];
[realm commitWriteTransaction];
[realm beginWriteTransaction];
for(ArticleModel *article in responseModel.articles){
ArticleRealm *articleRealm = [[ArticleRealm alloc] initWithMantleModel:article]; // (4)
[realm addObject:articleRealm];
}
[realm commitWriteTransaction];
dispatch_async(dispatch_get_main_queue(), ^{ // (5)
RLMRealm *realmMainThread = [RLMRealm defaultRealm]; // (6)
RLMResults *articles = [ArticleRealm allObjectsInRealm:realmMainThread];
self.articles = articles; // (7)
[self.tableView reloadData];
});
}
});
} failure:^(NSError *error) {
self.articles = [ArticleRealm allObjects];
[self.tableView reloadData];
}];
首先,API利用请求model(1)调用(2),返回的模型里包含文章的列表.为了在Realm里存储这些文章,我们需要在循环(4)里创建一个Realm对象.多个对象的写入,需要在子线程中进行操作(3).现在所有文章都存储在了Realm中,我们将它们赋值于类的self.articles(7)里.稍后我们将要在主线程的TableView的datasource方法里使用.从主线程中取出Realm中的数据是安全的(5).在新的线程中通过创建新的RLMRealm对象(6)来读取数据库.
如果从API中获取最新的文章失败,就会从failure block中读取本地数据.
- 后记
这篇教程中我们学到了如何使用Mantle(Cocoa和Cocoa Touch的模型库),来同远程API数据交互.我们还学到了使用Realm数据库来存储Mantle模型对象.
如果你想看看这个程序,可以从这里下载代码.运行前,需要替换相关的API key.
我觉得我需要一个校对😭
Girl学iOS100天 第6天
