Overcoat 是一个小巧但功能强大的库，使得创建 REST 客户端变得简单且有趣。它提供了一个简单的 API 来发送请求并将响应映射到模型对象。

Overcoat 基于 AFNetworking 构建，并使用 Mantle 将响应映射到普通或 Core Data 模型对象。

如果您需要了解关于 Mantle 的更多信息，我们推荐以下资源

1. 简介.
2. 使用 Mantle 和 AFNetworking 构建更好的 Web 客户端.

Overcoat 3.0 是最新主要版本，引入了几项破坏 API 的更改以支持封装和错误响应、Core Data 序列化和一个新的将响应映射到模型对象的方法。

您可以在 这里 查看 Overcoat 的使用情况。欢迎您将您的项目/应用添加到这个维基页面中。

需求

Overcoat 支持 OS X 10.8+ 和 iOS 6.0+。《code>NSURLSession 支持如 OVCHTTPSessionManager 和 OVCManagedHTTPSessionManager 需要 OS X 10.9+ 或 iOS 7.0+。

安装

将以下内容添加到您的 Podfile 中，并运行 $ pod install。

pod 'Overcoat', '~>3.0'

如果您尚未安装或集成 CocoaPods 到项目中，您可以在 这里 学习如何操作。

如果您是从 Overcoat 2.x 升级而来，请查看 迁移说明

注意

Mantle 目前支持 Mantle 1.x 和 2.x。使用 CocoaPods 安装时默认选择 Mantle 2.x。如果您想继续使用 Mantle 1.x，您还需要在 Podfile 中添加 pod 'Mantle', '~> 1.5'。

示例代码

Overcoat 包含一个简单的 Twitter 客户端，展示了以下新特性

• 将模型类映射到资源路径。
• 指定错误模型类。
• Core Data 序列化。
• Promises。

您可以在 这里 找到示例代码。请注意，您需要运行 pod install 安装所有依赖项。

使用

创建客户端类

外套提供了4个不同的类别来在创建自己的客户端时使用作为子类

这两个类具有相同的API，但针对OS X 10.9+ 或 iOS 7.0+ 的开发者被鼓励子类化 OVCHTTPSessionManager（如果您需要Core Data支持，则为 OVCManagedHTTPSessionManager）。针对OS X 10.8 或 iOS 6.0 的开发者必须子类化 OVCHTTPRequestOperationManager（如果您需要Core Data支持，则为 OVCManagedHTTPRequestManager）。

#import <Overcoat/Overcoat.h>

@interface TwitterClient : OVCHTTPSessionManager
...
@end

指定模型类别

要指定响应应如何映射到模型类别，您必须重写 +modelClassesByResourcePath 并返回将资源路径映射到模型类别的字典。

+ (NSDictionary *)modelClassesByResourcePath {
    return @{
        @"statuses/*": [Tweet class],
        @"users/*": [TwitterUser class],
        @"friends/ids.json": [UserIdentifierCollection class],
        @"followers/ids.json": [UserIdentifierCollection class]
    };
}

您不需要指定完整的路径，并且可以使用 * 和 ** 来匹配任何文本，或使用 # 来匹配仅数字。

如果使用 * 和 ##，它们是 严格路径匹配，因此 路径组件的数量必须相等。 ** 仅匹配任何文本，没有路径组件的数量限制。

封装和错误响应

不同的REST API有不同的处理状态和其他元数据的方式。

纯REST服务，如 Twitter，使用HTTP状态代码和特定的JSON响应来通信错误；以及HTTP头部的其他元数据，如速率限制。对于此类服务，您可能需要重写 +errorModelClass 以将错误响应映射到您自己的模型。

+ (Class)errorModelClass {
    return [TwitterErrorResponse class];
}

其他服务，如 App.net，使用封装响应，这是一个顶层JSON响应，包含请求的数据和额外的元数据。对于此类服务，您必须创建自己的 OVCResponse 子类并指定数据键路径。

@interface AppDotNetResponse : OVCResponse
...
@end

@implementation AppDotNetResponse
+ (NSString *)resultKeyPathForJSONDictionary:(NSDictionary *)JSONDictionary {
    return @"data";
}
@end

然后，您可以通过重写 +responseClass 来指定客户端使用的响应类。

+ (Class)responseClass {
    return [AppDotNetResponse class];
}

Core Data序列化

要支持Core Data序列化，您必须使用类似以下行的CoreData subspec

# Work with Mantle 2.x
pod 'Overcoat/CoreData', '~>3.0'
# Work with Mantle 1.x
pod 'Overcoat/CoreData/Mantle1', '~>3.0'

并且主要类将更改为以OVCManaged为前缀的类。 （例如，OVCHTTPReqeustOperationManager -> OVCManagedHTTPRequestOperationManager）

如果您使用有效的NSManagedObjectContext初始化客户端，它将自动将响应中解析的任何模型对象（如果模型支持Core Data序列化，即实现MTLManagedObjectSerializing）持久化。

请注意，如果您提供具有NSMainQueueConcurrencyType的上下文，则将创建一个私有上下文以在后台执行插入。

您可以在提供的示例中看到Core Data序列化的实际应用：示例。

制作HTTP请求

OVCHTTPRequestOperationManager 和 OVCHTTPSessionManager 提供了相同的HTTP请求方法。

// Lookup Twitter users
NSDictionary *parameters = @{
    @"screen_name": @"gonzalezreal",
    @"user_id": @"42,3141592"
};

[twitterClient GET:@"users/lookup.json" parameters:parameters completion:^(OVCResponse *response, NSError *error) {
    NSArray *users = response.result; // This is an array of TwitterUser objects!
}];

请注意，Overcoat会自动将JSON解析为模型对象，也就是说，在这种情况下，response.result 包含了 TwitterUser 对象的数组。

ReactiveCocoa

从2.0版本开始，Overcoat增加了对 ReactiveCocoa 的支持。

在您的 Podfile 中添加以下内容以安装支持ReactiveCocoa的Overcoat

pod 'Overcoat/ReactiveCocoa', '~>3.0'

现在您可以在发送HTTP请求时获取冷信号来处理响应

#import <Overcoat/ReactiveCocoa+Overcoat.h>
...
[[twitterClient rac_GET:@"users/lookup.json" parameters:parameters] subscribeNext:^(OVCResponse *response) {
    ...
} error:^(NSError *e) {
    ...
}];

PromiseKit

如果您正在寻找处理异步调用的一种更好的方式，但还没有准备好采用ReactiveCocoa，您可以尝试 PromiseKit。

在您的 Podfile 中添加以下内容以安装支持PromiseKit的Overcoat

pod 'Overcoat/PromiseKit', '~>3.0'

现在您在发送HTTP请求时可以得到 PMKPromise 对象

#import <Overcoat/PromiseKit+Overcoat.h>
...
[twitterClient GET:@"users/lookup.json" parameters:parameters].then(^(OVCResponse *response) {
    return response.result;
});

测试库

为了构建库并运行单元测试，您首先需要安装2个工具：cocoapods 和 xctool

• cocoapods: https://cocoapods.org.cn
• xctool: https://github.com/facebook/xctool

设置好这些工具（或者您已经拥有了这些工具）后，您可以运行测试

make test

检查 Makefile 来运行其他测试目标。

联系方式

• Guillermo Gonzalez，@gonzalezreal
• sodastsai，@sodastsai

许可证

Overcoat是在MIT许可证下提供的。请参阅 LICENSE.md。