Patron

使用 JSON HTTP API

程序通常通过 HTTP 进行通信。在这种通信中，有效负载的事实标准表示法是 JSON。Patron Swift 包提供了一个简单的接口来与 HTTP 服务器发送和接收数据。它的目的是减少冗余的客户端代码，同时保持简单。

• Patron

Patron 对象表示远程 HTTP JSON 服务端点。

• JSONService

JSONService 协议定义了一个 JSON 服务。

• PatronError

Patron 类是表示远程 HTTP JSON 服务端点的便捷方式。Patron 对象通过 GET 和 POST HTTP 方法提供对特定主机上单个服务的访问。它假定两个方向的有效负载都是 JSON。

由于 Patron 在调用线程上序列化 JSON 有效负载，因此最好不要从主线程使用它，相反，我建议您从 Operation 中运行它，或者将闭包分派到另一个队列。通常需要更多的工作，例如序列化，这应该从主线程卸载。

init(URL baseURL: URL, session: URLSession, log: OSLog)

为指定的 URL 上的服务创建一个客户端。

• URL 服务的 URL。
• session 用于 HTTP 请求的会话。
• log 要使用的日志，默认为共享的禁用日志。

返回新初始化的 Patron 客户端。

@discardableResult func get(
  path: String,
  cb: @escaping (AnyObject?, URLResponse?, Error?) -> Void
) -> URLSessionTask

向远程 API 发起 GET 请求。

• path URL 路径，包括第一个斜杠，例如 "/user"。
• cb 接收 JSON 结果作为其第一个参数的回调，后跟 response 和 error。所有回调参数都可能为 nil。

一个正在执行的 URLSessionTask。

在 GitHub 上搜索 Swift Repos 并打印其名称。

import Foundation
import Patron

let github = URL(string: "https://api.github.com")!
let patron = Patron(URL: github, session: URLSession.shared)

patron.get(path: "/search/repositories?q=language:swift") { json, res, er in
  let repos = json!["items"] as! [[String : AnyObject]]
  let names = repos.map { $0["name"]! }
  print(names)
}

在此 repo 中包含的 Playground 中查找此示例。

如果您不想自己将路径连接在一起，则可以传递 URL 查询项。

@discardableResult func get(
  path: String,
  with query: [URLQueryItem],
  cb: @escaping (AnyObject?, URLResponse?, Error?) -> Void
) throws -> URLSessionTask

使用查询字符串向远程 API 发起 GET 请求。

• path URL 路径，包括第一个斜杠，例如 "/user"。
• query 来自 Foundation 的 URL 查询项数组。
• cb 接收 JSON 结果作为其第一个参数的回调，后跟 response 和 error。所有回调参数都可能为 nil。

一个正在执行的 URLSessionTask。

为了获得更多控制，还有一种带有 allowsCellularAccess 和 cachePolicy 参数的替代方法。

@discardableResult func get(
  path: String,
  allowsCellularAccess: Bool,
  cachePolicy: URLRequest.CachePolicy,
  cb: @escaping (AnyObject?, URLResponse?, Error?) -> Void
) -> URLSessionTask

• allowsCellularAccess 如果允许请求使用蜂窝无线电，则为 true。
• cachePolicy 请求的缓存策略。

@discardableResult func post(
  path: String,
  json: AnyObject,
  cb: @escaping (AnyObject?, URLResponse?, Error?) -> Void
) throws -> URLSessionTask

向远程 API 发起 POST 请求。

• path URL 路径。
• json 作为此请求正文发送的有效负载。
• cb 接收 JSON 结果作为其第一个参数的回调，后跟 response 和 error。所有回调参数都可能为 nil。

一个正在执行的 URLSessionTask。

PatronError.InvalidJSON，如果潜在的 json 有效负载无法通过 NSJSONSerialization 序列化为 JSON。

var host: String { get }

远程服务的主机名。

var status: (Int, TimeInterval)? { get }

上次 URLSession 或 JSONSerialization 错误代码，以及它在 Unix 时间发生的时间戳，自 1970 年 1 月 1 日 00:00:00 UTC 以来的秒数。下一个成功的请求会将 status 重置为 nil。

为了进行测试，我们运行一个小的 Node.js 服务器 – 在 Tests/Server 中找到它。

$ make test

📦 将 https://github.com/michaelnisi/patron 添加到您的包清单中。

MIT