Vapor文档学习卅二: HTTP -Client

HTTP的客户端用于向远程服务器发送请求。下面我们看一个简单的外部请求。

QuickStart

让我们进入一个简单的HTTP请求，这是Vapor的GET请求：

let query = ...
let spotifyResponse = try drop.client.get("https://api.spotify.com/v1/search?type=artist&q=\(query)")
print(spotifyR)

Clear Up

上面的url理解起来可能有点困难，我们使用query做下简单的清理：

try drop.client.get("https://api.spotify.com/v1/search", query: ["type": "artist", "q": query])

Continued

除了GET， Vapor还支持更多常见的HTTP功能：GET, POST, PUT, PATCH, DELETE。

POST as json

let jsonBytes = myJSON.makeBytes()
try drop.client.post("http://some-endpoint/json", headers: ["Auth": "Token my-auth-token"], body: .data(jsonBytes))

POST as x-www-form-urlencoded

try drop.client.post("http://some-endpoint", headers: [
  "Content-Type": "application/x-www-form-urlencoded"
], body: Body.data( Node([
  "email": "[email protected]"
]).formURLEncoded()))

Full Request

为了获取其他功能或者自定义方法，可以直接使用底层的request函数。

public static func get(_ method: Method,
                       _ uri: String,
                       headers: [HeaderKey: String] = [:],
                       query: [String: CustomStringConvertible] = [:],
                       body: Body = []) throws -> Response

下面调用这个接口：

try drop.client.request(.other(method: "CUSTOM"), "http://some-domain", headers: ["My": "Header"], query: ["key": "value"], body: [])

Config

在Config/clients.json文件中可以修改客户端的配置。

TLS

可以禁用主机和证书验证。

Note: 修改这些配置时请格外小心。

{
    "tls": {
        "verifyHost": false,
        "verifyCertificates": false
    }
}

Mozilla

默认情况下包含Mozilla证书来保证从安全站点获取内容。

{
    "tls": {
        "certificates": "mozilla"
    }
}

Advanced

除了我们的Droplet，我们还有手动使用或与client进行交互。以下是我们在Vapor中的默认实现：

let response = try Client.get("http://some-endpoint/mine")

我们可能注意到的第一件事是将TCPClientStream作为通用值。这将使得HTTP.Client在进行请求时可以使用底层连接。通过遵守底层ClientStream协议，HTTP.Client可以无缝地接收自定义实现的流。

Save Connection

到目前为止，我们都是通过类或者静态函数与Client进行交互，这允许我们在完成请求后断开连接，大多数情况下我们推荐这样使用。在一些高级情景下，我们可能需要重新连接，为此我们像下面那样初始化客户端并进行多次请求。

let pokemonClient = try drop?.client.make(scheme: "http", host: "pokeapi.co")
for i in 0...1 {
    let response = try pokemonClient?.get(path: "/api/v2/pokemon/", query: ["limit": 20, "offset": i])
    print("response: \(response)")
}

ClientProtocol

此前，我们专注于内置的HTTP.Client，但用户还可以通过遵守HTTP.ClientProtocol协议来包含自定义的客户端。我们来看看如何实现：

public protocol Responder {
    func respond(to request: Request) throws -> Response
}

public protocol Program {
    var host: String { get }
    var port: Int { get }
    var securityLayer: SecurityLayer { get }
    // default implemented
    init(host: String, port: Int, securityLayer: SecurityLayer) throws
}

public protocol ClientProtocol: Program, Responder {
    var scheme: String { get }
    var stream: Stream { get }
    init(scheme: String, host: String, port: Int, securityLayer: SecurityLayer) throws
}

通过实现这些基本功能，我们可以立即访问我们上面查看的公共的ClientProtocolapi。

Customize Droplet

如果我们引入了一个遵守HTTP.ClientProtocol的自定义的client，我们可以把它传给Droplet而不会改变应用的底层行为。
示例：

let drop = Droplet()

drop.client = MyCustomClient.self

之后你对drop.client的所有调用都会使用MyCustomClient.self：

drop.client.get(... // uses `MyCustomClient`