JustAPIs Swift SDK

概述

一个轻量级的 Swift SDK，通过 iOS 客户端连接到 JustAPIs 网关。

依赖项

开发/生产

在使用此框架时，您的项目中没有外部依赖项。

然而，此 SDK 是一个 Swift 动态框架，用 Swift 2.1 编写，需要最低部署目标为 iOS 8.0。

SDK 中使用的一些功能（例如元组、结构体）目前在 Objective-C 代码中并不可用。如果您想在 Objective-C 应用程序中使用此框架，您需要在您的 Swift 代码中自己将这些功能打包。

单元测试

如果您想对此框架进行单元测试，它需要 OHHTTPStubs 以便模拟请求。它已经作为子模块包含在这个存储库中，因此您可以运行

git submodule update --init

以使其可用。

介绍

SDK 的核心功能通过三个简单协议暴露：`Gateway`、`Request` 和 `Response`。

这些基本协议在 CoreTypes.swift 中定义。

一个 `Gateway` 代表您与单个 JustAPIs 服务器的连接。您可以向此网关发送 `Request`，并通过简单的回调闭包接收 `Response`。

SDK 包含两个 `Gateway` 的实现：

CompositedGateway

复合网关由几个可配置的可替换组件构建。

• 一个 `NetworkAdapter` 接受 `Request` 并在返回 `Response` 或错误之前将它们通过网络发送出去。默认的网络适配器是 `FoundationNetworkAdapter`，它使用 NSURLSession。

  如果您想使用不同的通信技术（例如AFNetworking、Alamofire、后台会话、缓存等），您可以编写一个简单的NetworkAdapter并将其插入CompositedGateway的构造函数中。

• 一个可选的RequestPreparer。一个RequestPreparer可以在网关级别修改请求。您可以使用它来在任何请求中插入令牌、应用默认标头、重新映射URL或将请求数据序列化为JSON或表单数据等标准格式。

  SDK中包含两个示例RequestPreparer。DefaultFieldsRequestPreparer可以应用于所有请求，在请求中添加缺失的查询参数或头字段。RequestPreparerClosureAdapter允许您提供一个简单的闭包来执行任何所需的操作。

• 一个可选的ResponseProcessor。一个ResponseProcessor可以在调用原始响应回调之前在网关级别修改响应。这为进行日志记录、处理错误或解析JSON或XML等常见响应格式提供了机会。

  SDK中包含两个示例ResponseProcessor。JsonResponseProcessor使用NSJSONSerialization反序列化所有响应的内容。ResponsePreparerClosureAdapter允许您提供一个简单的闭包来执行任何所需的操作。

• 一个可以缓存响应并在后续请求中返回它们而无需再次进行网络请求的CacheProvider。默认的CacheProvider是InMemoryCacheProvider，它使用Foundation的NSCache在内存中存储响应。

  如果您需要更持久的或更复杂的缓存，您可以实现自己的CacheProvider并在初始化CompositeGateway时传递它。

• 一个用于证书固定的可选的SSLCertificate。如果您提供了与您的服务器关联的公钥或证书，则在发送任何请求之前将验证其标识。

• 一个可选的DefaultRequestPropertySet，允许您自定义提交给网关的GET、POST、PUT和DELETE请求的默认选项。当使用网关的便利方法提交请求时，将使用这些默认值。如果您不提供自己的默认值，网关将使用在Request.swift中找到的GatewayDefaultRequestProperties。

JsonGateway

JsonGateway是为了方便而提供的网关实现。它只是一个包含默认JsonResponseProcessor的CompositedGateway。

设置

框架集成

手动

即将推出。

模块导入

将框架包含到您的项目中后，只需使用以下方法将模块导入到您自己的代码中：

import JustApisSwiftSDK

用法

提交请求

要向您的JustAPIs服务器提交请求，只需创建一个Gateway并提交一个Request。

这里有一个简单的示例

var gateway = CompositedGateway(baseUrl: NSURL(string:"http://my-justapi-server.local:5000/"))

gateway.get("/foo", params:["id":123], callback:
{ (result:RequestResult) in

  if let error = result.error
  {
     print("Received an error: \(error)")
     return
  }
  guard let response = result.response else
  {
     print("Received no response!")
     return
  }

  print("Received a response with HTTP status code: \(response.statusCode)")
})

在此示例中，您可以看到我们使用网关的get便利方法。

此方法使用尽可能少的参数准备并提交GET请求。为每个常见的HTTP方法（GET、POST、PUT、DELETE）都提供了一组这些便利方法。这些便利方法的完整列表可以在Gateway.swift中找到。

您也可以从头开始使用符合RequestProperties协议的任何对象来准备您的请求。MutableRequestProperties是为了您的方便提供的。您不需要调用便捷方法之一，只需将请求属性和回调传递给submitRequest方法即可。

请求队列

网关的每个实例都会限制请求，以确保在任何时候都不超过maxActiveRequests个请求正在运行（默认值为2）。如果您提交请求的速度超过它们的处理速度，可以通过pendingRequests属性访问待处理请求。

您可以在任何时候暂停和恢复请求队列。当暂停时，网关将不会启动已入列的新请求。当您离线时，您可能想暂停队列，并在恢复连接时恢复。

请求是不可变的，一旦提交给网关，就不能再修改。但是，您可以通过调用cancelRequest(...)来取消仍在挂起的请求。

自动内容类型解析

组合网关支持基于内容类型的自动解析。通过调用setParser(...)。您可以为在网关上遇到特定内容类型时运行注册一个ResponseProcessor。当内容类型为application/json时，JsonCompositedGateway使用此技术自动解析JSON响应。

您可以分配任意数量的内容类型解析器。

您可以通过将请求属性的applyContentTypeParsing设置为false来为任何请求禁用自动内容类型解析。

您可以通过将请求属性的contentTypeProperty设置为非空值，来强制将响应以特定的内容类型进行解释。此内容类型将用于替代响应头中返回的内容类型。

响应缓存

组合网关支持响应的缓存。您可以使用请求属性来控制缓存行为。

通过将allowCachedResponse设置为false，确保执行新的网络请求。

您可以通过将cacheResponseWithExpiration设置为0来禁用响应的缓存。将其设置为更高的值表示缓存的响应将被保留的秒数。

您可以通过设置customCacheIdentifier属性来为请求提供自定义缓存标识符。默认情况下，仅使用方法、路径和查询参数来区分不同的请求。如果您的头部或正文对于缓存的响应来说是相关的，您需要设置一个自定义缓存标识符，以适当捕获这些信息。一个例子可能是，如果您使用GET或POST请求的正文发送搜索参数，并希望缓存响应。

接收JSON响应

如果您的JustAPI端点提供JSON格式的响应，您可以使用JsonGateway或将JsonResponseProcessor设置为一个CompositedGateway内容类型解析器。

var gateway = JsonGateway(baseUrl: NSURL(string:"http://my-justapi-server.local:5000/"))

gateway.get("/foo", params:["id":123], callback:
{ (result:RequestResult) in

  if let error = result.error
  {
     print("Received an error: \(error)")
     return
  }
  guard let response = result.response else
  {
     print("Received no response!")
     return
  }
  guard let jsonData = response.parsedBody else
  {
      print:("No parsed body data found!")
      return
  }
  print("Received a response with JSON content: \(jsonBody)")
})

请求准备器

请求准备器允许您在请求提交给您的网关实例之后，但在它们被添加到请求队列之前对其进行修改。

常见的用途包括向请求添加额外的头部、基于查询参数构建并添加身份验证令牌，或使用特定格式编码正文数据。

响应处理器

响应处理器非常灵活，可以在响应通过回调之前对其进行修改、观察或拒绝。

所有响应处理器都公开了一个异步的 processResponse(...) 方法，该方法接收当前的（不可变）响应，并最终与响应和/或错误一起调用响应处理器回调。 processResponse 总是在主线程上调用。

ResponseProcessorClosureAdapter 是一个便利的包装器，当您希望对响应执行快速且简单的操作时（例如，如果预期的标头或响应字段无效，则进行错误信号）可使用它。它包装了一个简单的、同步的闭包。

CompoundResponseProcessor 允许您轻松地将一系列响应处理器链接起来，以便它们按顺序运行。如果有任何响应处理器提示错误，则其余部分将被跳过。

开发

该 SDK 设计得轻量且模块化，这样您就可以在不直接修改其代码的情况下增强和修改其功能。

但是，如果您想修改 SDK，欢迎您clone或fork此存储库。您还需要修改您的应用程序，确保它们集成您自己的代码，而不是此存储库中托管的内容。

单元测试确实要求OHHTTPStubs可用，以便模拟请求，但它作为git子模块提供。有关更多信息，请参阅 依赖关系。