简介

XBToolkit 是一个提供快速且高度定制化检索和反序列化 JSON 源的框架。它主要依赖于 AFNetworking 进行网络层和 Mantle 进行反序列化层。

安装

XBToolkit 可以通过 CocoaPods 或将源文件包含到您的项目中安装。

如果您使用 Cocoapods，请将以下行添加到 Podfile 中安装 XBToolkit：

pod XBToolkit

用法

以下是示例，展示了如何将 JSON 表示的远程对象映射到本地类的实例

反序列化远程 JSON 数组

// 1. Create an HTTP client:
id httpClient = [XBHttpClient httpClientWithBaseUrl:@"http://myfancyblog.com"];

// 2. Instantiate an dataMapper, allowing the response to be deserialized to a given class (e.g. WPAuthor):
XBJsonToArrayDataMapper *dataMapper = [XBJsonToArrayDataMapper mapperWithRootKeyPath:@"authors" typeClass:[WPAuthor class]];

// 3. Instantiate an dataLoader from your HTTP client and a given resourcePath:
XBHttpJsonDataLoader *dataLoader = [XBHttpJsonDataLoader dataLoaderWithHttpClient:httpClient resourcePath:@"/wp-json-api/get_author_index/" dataMapper:dataMapper];

// 4. Create the data source from the dataLoader and the dataMapper:
XBReloadableArrayDataSource *dataSource = [XBReloadableArrayDataSource dataSourceWithDataLoader:dataLoader];

// 5. Load the data:
[dataSource loadData:^(id operation) {
    NSLog(@"%@", dataSource.array.count); // Will output the number of authors of myfancyblog.com
}];

反序列化远程 JSON 对象

// 1. Create an HTTP client:
id httpClient = [XBHttpClient httpClientWithBaseUrl:@"http://myfancyblog.com"];

// 2. Instantiate an dataMapper, allowing the response to be deserialized to a given class (e.g. WPPost):
XBJsonToObjectDataMapper *dataMapper = [XBJsonToObjectDataMapper mapperWithRootKeyPath:@"post" typeClass:[WPPost class]];

// 3. Instantiate an dataLoader from your HTTP client and a given resourcePath:
XBHttpJsonDataLoader *dataLoader = [XBHttpJsonDataLoader dataLoaderWithHttpClient:httpClient resourcePath:@"/wp-json-api/get_post/?slug=xbtoolkit-is-so-sweet" dataMapper:dataMapper];

// 4. Create the data source from the dataLoader and the dataMapper:
XBReloadableObjectDataSource *dataSource = [XBReloadableObjectDataSource dataSourceWithDataLoader:dataLoader];

// 5. Load the data:
[dataSource loadData:^(id operation) {
    NSLog(@"%@", dataSource.object.slug); // Prints "my-great-post"
}];    

如何反序列化到特定的数据模型

表示您的数据模型的类应继承自 MTLModel 并定义所有对象包含的属性。例如，假设我们有以下 JSON 对象：

{
    "status": "ok",
    "post": {
        "id": 14332,
        "type": "post",
        "slug": "xbtoolkit-is-nice",
        "url": "http:\/\/myfancyblog.com\/2013\/05\/30\/xbtoolkit-is-cool\/",
        "status": "publish",
        "title": "XBToolkit is nice",
        "title_plain": "XBToolkit is nice",
        "content": "XBToolkit is nice"
}

如果我们想将该对象反序列化为 WPPost 类，我们需要创建以下代码的 WPPost 类：

// WPPost.h

#import <Foundation/Foundation.h>
#import <Mantle/Mantle.h>

@interface WPPost : MTLModel<MTLJSONSerializing>

@property (nonatomic, strong) NSNumber *identifier;
@property (nonatomic, strong) NSString *type;
@property (nonatomic, strong) NSString *slug;
@property (nonatomic, strong) NSString *url;
@property (nonatomic, strong) NSString *status;
@property (nonatomic, strong) NSString *title;
@property (nonatomic, strong) NSString *title_plain;
@property (nonatomic, strong) NSString *content;

@end

// WPPost.m

#import "WPPost.h"

@implementation WPPost

+ (NSDictionary *)JSONKeyPathsByPropertyKey
{
    return nil;
}

@end

mappings 类方法必须包含特定于类的配置。由于 XBToolkit 依赖于 Mantle 进行对象的映射，您可以在项目的说明页面中找到有关映射配置的更详细信息。

分解

HTTP 客户端

httpClient (XBHttpClient) 负责与远程源建立 HTTP 连接。

数据加载器

dataLoader 对象负责从源检索数据。XBToolkit 已包含便利子类，以提供最常见的数据加载器。这些包括

• XBHttpJsonDataLoader：提供一个数据加载器，从远程 JSON 资源检索其数据。可以通过以下工厂创建 XBHttpLoader 实例：

+ (XBHttpJsonDataLoader *)dataLoaderWithHttpClient:(XBHttpClient *)httpClient resourcePath:(NSString *)path

数据映射器

dataMapper 对象允许将资源通过以下部分所述的方式 反序列化到特定数据模型 映射到本地数据模型。框架中包含的便捷子类有：

• XBJsonToObjectDataMapper：将 JSON 对象转换为本地实例。
• XBJsonToArrayDataMapper：将 JSON 数组转换为本地的 NSArray。

数据源

dataSource 提供了访问对象实例的托管接口。以下数据源包含在 XBToolkit 中：

• XBObjectDataSource：这是最简单的 dataSource 形式，它基本上是对象的包装器。
• XBReloadableObjectDataSource：这是一个提供重新加载dataSource中包装的对象能力的类。这对于所有由 dataLoader 和 dataMapper 创建的可重新加载对象数据源来说是有意义的。此类对象可以通过以下方式实例化：

+ (XBReloadableObjectDataSource *)dataSourceWithDataLoader:(XBDataSource *)dataSource dataMapper:(XBDataMapper *)dataMapper;

• XBArrayDataSource：XBArrayDataSource提供了访问有序元素列表的数组-like 方法。
• XBReloadableArrayDataSource：这是一个提供在dataSource中重新加载包含的元素的类。这对于从 dataLoader 和 dataMapper 创建的数据源来说是有意义的。此类对象可以通过以下方式实例化：

+ (XBReloadableArrayDataSource *)dataSourceWithDataLoader:(XBDataSource *)dataSource dataMapper:(XBDataMapper *)dataMapper;

团队

作者

• Alexis Kinsella (akinsella) - Xebia IT Architects
• Simone Civetta (viteinfinite) - Xebia IT Architects

许可证

Apache 许可证，版本 2.0