SwiftyRequest

SwiftyRequest 是一个为 Swift 构建的 HTTP 客户端。

最新发布的 SwiftyRequest 基于 Swift-NIO 的 async-http-client 构建。

• 特性
• 安装
• 用法
• 断路器集成
• 响应方法
• 从 SwiftyRequest v2 迁移到 v3

• 多种响应方法（例如 Data、Object、Array、String 等），以消除应用程序中的样板代码。
• 直接检索 Codable 类型。
• JSON 编码和解码。
• 与 CircuitBreaker 库集成。
• 身份验证令牌。
• 客户端证书支持（双向 SSL）。
• Multipart form data。

最新版本的 SwiftyRequest 需要 Swift 5 或更高版本。

Swift 4 支持在 SwiftyRequest 的 2.x 版本中提供。

要在您的 Swift 应用程序中利用 SwiftyRequest 包，您应该在 Package.swift 文件中为其指定依赖项

将 SwiftyRequest 添加到应用程序的 Package.swift 文件中的 dependencies 中。将 "x.x.x" 替换为最新的 SwiftyRequest release。

.package(url: "https://github.com/Kitura/SwiftyRequest.git", from: "x.x.x")

将 SwiftyRequest 添加到你的 target 的 dependencies 中

.target(name: "example", dependencies: ["SwiftyRequest"]),

要使用 SwiftyRequest 发起出站 HTTP 调用，请创建一个 RestRequest 实例。 method 参数是可选的（默认为 .get），url 参数是必需的。

RestRequest 的用法示例

import SwiftyRequest

let request = RestRequest(method: .get, url: "http://myApiCall/hello")
request.credentials = .basicAuthentication(username: "John", password: "12345")

您可以自定义 HTTP 请求中的以下参数

• headerParameters：构成请求消息头部的 HTTP 头部字段。
• credentials：请求的 HTTP 身份验证凭据。
• acceptType：HTTP Accept 头部，默认为 application/json。
• messageBody：请求的 HTTP 消息体。
• productInfo：HTTP User-Agent 头部。
• circuitParameters：一个 CircuitParameters 对象，其中包含对后备函数的引用，该后备函数将在断路器快速失败时被调用（请参阅 断路器集成）。
• contentType：HTTP Content-Type header，默认为 application/json。
• method：请求中指定的 HTTP 方法，默认为 .GET。
• queryItems：要附加到 URL 的任何查询参数。

我们收到的 result 对象类型为 Result<RestResponse<String>, Error>，因此我们可以执行 switch 以确定网络调用是否成功

request.responseString { result in
    switch result {
    case .success(let response):
        print("Success")
    case .failure(let error):
        print("Failure")
    }
}

URL 可以使用 {keyName} 语法进行模板化，允许单个 RestRequest 实例与不同的参数重用。

在此示例中，我们使用两个模板参数调用响应方法，这些参数将用于替换 URL 中的 {state} 和 {city} 值

let request = RestRequest(url: "http://api.weather.com/api/123456/conditions/q/{state}/{city}.json")

request.responseData(templateParams: ["state": "TX", "city": "Austin"]) { result in
	// Handle response
}

在此示例中，我们使用查询参数调用响应方法，该参数将附加到幕后 url 上，以便 RestRequest 使用以下 url 执行：http://api.weather.com/api/123456/conditions/q/CA/San_Francisco.json?hour=9。请求 URL 中已指定的任何查询项都将被替换

let request = RestRequest(url: "http://api.weather.com/api/123456/conditions/q/CA/San_Francisco.json")

request.responseData(queryItems: [URLQueryItem(name: "hour", value: "9")]) { result in
	// Handle response
}

SwiftyRequest 具有内置功能，可以利用 CircuitBreaker 库来提高应用程序的稳定性。要使用此功能，请将 CircuitParameters 对象分配给 circuitParameters 属性。此对象将包含对后备函数的引用，该后备函数将在断路器快速失败时被调用。

这是一个后备闭包的示例

let breakerFallback = { (error: BreakerError, msg: String) in
    print("Fallback closure invoked... circuit must be open.")
}

我们初始化 CircuitParameters 对象并创建一个 RestRequest 实例。您需要为 CircuitParameters 设置的唯一必需值是 fallback（其他所有内容都有默认值）。

let circuitParameters = CircuitParameters(timeout: 2000,
                                          maxFailures: 2,
                                          fallback: breakerFallback)

let request = RestRequest(method: .GET, url: "http://myApiCall/hello")
request.circuitParameters = circuitParameters

此时，您可以使用下面部分中提到的任何响应方法。

RestRequest 提供了许多 response 函数，这些函数使用包含响应或错误的 Result 回调。

要调用请求并接收响应，您可以使用 response 函数。完成处理程序将使用类型为 Result<HTTPClient.Response, Error> 的结果回调。

RestRequest 提供了额外的便利方法，您可以根据预期的响应正文类型使用这些方法

• responseData 要求响应包含正文，并使用 Result<RestResponse<Data>, Error> 回调。
• responseObject<T: Decodable> 将响应正文解码为指定的类型，并使用 Result<RestResponse<T>, Error> 回调。
• responseString 将响应正文解码为 String，并使用 Result<RestResponse<String>, Error> 回调。
• responseDictionary 将响应正文解码为 JSON，并使用 Result<RestResponse<[String: Any]>, Error> 回调。
• responseArray 将响应正文解码为 JSON 数组，并使用 Result<RestResponse<[Any]>, Error> 回调。
• responseVoid 不期望响应正文，并使用 Result<HTTPClient.Response, Error> 回调。

let request = RestRequest(method: .get, url: "https://:8080/users/{userid}")

request.responseObject(templateParams: ["userid": "1"]) { (result: Result<RestResponse<User>, RestError>) in
    switch result {
    case .success(let response):
        let user = response.body
        print("Successfully retrieved user \(user.name)")
    case .failure(let error):
        if let response = error.response {
            print("Request failed with status: \(response.status)")
        }
        if let responseData = error.responseData {
            // Handle error response body
        }
    }
}

与 v2 版本相比，SwiftyRequest v3 中的 API 有许多更改

• RestRequest 初始化程序参数 containsSelfSignedCert 已重命名为 insecure，以更好地反映其用途（关闭 SSL 证书验证）。旧名称已被弃用，可能会在未来的版本中删除。
• responseData（等）的 completionHandler 回调已从 (RestResponse<Data>) -> Void 更改为 (Result<RestResponse<Data>, RestError>) -> Void。
• JSONDecodable 和 JSONEncodable 类型已被删除，改为直接使用 Codable。 responseObject 函数允许您在响应中接收 Codable 对象。
• 添加了用于处理原始 JSON 的便捷函数。 responseDictionary 和 responseArray 允许分别检索 JSON 作为 [String: Any] 和 [Any]，并且可以通过设置 request.messageBodyDictionary 或 request.messageBodyArray 属性来执行原始 JSON 的发送。
• RestError 类型现在在 .failure case 中显式返回。如果错误与具有非成功状态代码的响应有关，您可以使用 error.response 访问响应。如果响应还包含正文数据，则可以通过 error.responseData 检索它。

创建 RestRequest 时指定 ClientCertificate 以启用在安全请求时呈现客户端证书（双向 SSL）。

证书可以以 PEM 格式提供 - 可以来自文件、字符串或 Data，以及可选的密码。PEM 数据应包含证书及其对应的私钥。如果私钥已加密，则应在构造 ClientCertificate 时指定相应的密码。

如果您需要处理其他格式的证书，您可以直接从 NIOSSLCertificate 和 NIOSSLPrivateKey 创建 ClientCertificate。有关这些类型的更多信息，请参阅 async-http-client 项目的文档。

有关更多信息，请访问我们的 API 参考。

我们喜欢讨论服务器端 Swift 和 Kitura。加入我们的 Slack 与团队会面！

此库在 Apache 2.0 许可下获得许可。完整许可文本可在 LICENSE 中找到。