一个类型安全的 iOS HTTP 客户端，受 Retrofit 启发。

介绍

Restless 将您的 HTTP API 转换为一个 Objective-C 协议。

只需定义一个从 DRWebService 继承的协议。

@protocol GitHubService <DRWebService>

@GET("/users/{user}/repos")
- (NSURLSessionDataTask*)listRepos:(NSString*)user
                          callback:DR_CALLBACK(NSArray<GitHubRepo*>*)callback;

@end

DRRestAdapter 类生成 GitHubService 协议的实现。

DRRestAdapter* ra = [DRRestAdapter restAdapterWithBlock:^(DRRestAdapterBuilder *builder) {
    builder.endPoint = [NSURL URLWithString:@"https://api.github.com"];
}];

NSObject<GitHubService>* service = [ra create:@protocol(GitHubService)];

从创建的 GitHubService 返回的每个 NSURLSessionTask 都可以异步地向远程服务器发送 HTTP 请求。

NSURLSessionDataTask* task = [service listRepos:@"natep"
                                       callback:^(NSArray<GitHubRepo*>* result,
                                                  NSURLResponse *response,
                                                  NSError *error)
{
    // response handling ...
}];

[task resume];

使用注解来描述 HTTP 请求。

API 声明

接口方法和其参数上的注解指示请求将如何处理。

请求方法

每个方法都必须有一个提供请求方法和相对 URL 的 HTTP 注解。有六个内置注解：GET、POST、PUT、DELETE、HEAD 和 PATCH。资源的相关 URL 在注解中指定。

@GET("/users/list")

您还可以在 URL 中指定查询参数。

@GET("/users/list?sort=desc")

URL 操作

可以通过使用方法上的替换块和参数来动态更新请求 URL。替换块是包围在大括号 {} 中的字母数字字符串。方法将查找匹配该字符串的参数名称，并用其值替换。

@GET("/users/{user}/repos")
- (NSURLSessionDataTask*)listRepos:(NSString*)user
                          callback:DR_CALLBACK(NSArray<GitHubRepo*>*)callback;

任何未消费（例如，在替换中使用）的方法参数都包含在 URL 的查询项中。

表单编码 URLencoded

如果您使用 @FormUrlEncoded 注解，则未使用的参数将包括在编码的体中，而不是 URL 查询中。

请求体

可以使用带有参数名称的 @Body 方法注解指定一个对象作为 HTTP 请求体的使用。

@POST("/users/new")
@Body("user")
- (NSURLSessionUploadTask*)createUser:(User*)user 
                             callback:DR_CALLBACK(User*)callback;

对象还将使用在 DRRestAdapter 实例上指定的转换器进行转换。默认情况下使用 JSON 转换器。

回调

DR_CALLBACK() 是一个特殊的宏，它接受你想返回的对象类型，并创建一个类似 NSURLSessionTask 风格的回调，其中第一个回调参数是该类型的对象。在上面的 listRepos:callback: 示例中，指定了 NSArray 类型的回调。当你调用 listRepos:callback: 方法时，代码补全会自动将其展开为以下回调

^(NSArray<GitHubRepo*>* result, NSURLResponse *response, NSError *error)

库将尝试将响应转换为在构建器中指定的对象类型，使用转换器进行转换。在这种情况下，是一个 NSArray，包含了 GitHubRepo 对象。

回调应该是你方法中的最后一个参数。

NSURLSessionTask

方法的返回类型定义了你希望方法为你构建哪种类型的 NSURLSessionTask。

支持 NSURLSessionDataTask、NSURLSessionDownloadTask 和 NSURLSessionUploadTask，但你应该确保传递给 DR_CALLBACK() 的值适合该任务。例如，在请求 NSURLSessionDownloadTask 时，你应该传递 NSURL*。完成时，回调的该参数将是一个包含下载的临时文件的URL。

头信息操作

你可以使用 @Headers 注解为方法设置静态头信息。

@Headers({ "Accept": "application/vnd.github.v3.full+json", "User-Agent": "Restless-Sample-App" })
@GET("/users/{username}")
- (NSURLSessionDataTask*)getUser:(NSString*)username
                        callback:DR_CALLBACK(User*)callback;

@Headers 参数的值始终应该是 JSON 对象（也称为字典）。头信息值也可以使用参数替换。

认证

对于某些认证方法，你可以简单地给 Restless 使用的 NSURLSession 分配一个代理，并实现 URLSession:didReceiveChallenge:completionHandler:。

如果你使用基本或摘要认证，你可以通过在 NSURLSessionConfiguration 中提供它，为会话中的所有请求设置该认证头信息。

NSURLSessionConfiguration *sessionConfig = [NSURLSessionConfiguration defaultSessionConfiguration];
[sessionConfig setHTTPAdditionalHeaders:@{ @"Authorization": authHeader }];
NSURLSession *session = [NSURLSession sessionWithConfiguration:sessionConfig
                                                      delegate:nil
                                                 delegateQueue:nil];

限制

• 尽管这个库受到了 Retrofit 的启发，但它还没有实现所有功能。特别是，还没有原生支持多部分编码的正文。

• 当前的解析逻辑不支持多行注解。因此，你不能有一个跨越多行的单个注解。

• 当前的解析逻辑很简单，并且不懂宏。因此，你不应该在你的 Web 服务协议声明中使用它们。类型定义可能或可能不工作。

• 性能还没有被评估。这将是未来版本的重点。

安装

建议你使用 Cocoapods 安装此库。

pod 'Restless'

安装后，你需要给你的项目添加一个新的 Run Script Build Phase，它将运行以下命令

"${PODS_ROOT}"/Restless/Restless/Scripts/generate.sh

许可证

Copyright (c) 2015 Digital Rickshaw LLC

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.