FTAPIKit

使用 Codable 的声明式和泛型 REST API 框架。使用 URLSession 和 JSON 编码器/解码器的标准实现。可以轻松扩展到您的异步框架或网络堆栈。

安装

使用 Swift Package Manager 时，请使用 Xcode 11+ 安装，或将以下行添加到您的依赖项中

.package(url: "https://github.com/futuredapp/FTAPIKit.git", from: "1.5.0")

使用 CocoaPods 时，将以下行添加到您的 Podfile

pod 'FTAPIKit', '~> 1.5'

特性

该库的主要特性是提供类似文档的 API 用于定义 Web 服务。这是通过在 Swift 中使用声明式和面向协议的编程来实现的。

该框架提供了两个核心协议，反映了物理基础设施

Server 协议，定义单个 Web 服务。
Endpoint 协议，定义资源的访问点。

结合符合 Server 和 Endpoint 类型的实例，我们可以构建请求。 URLServer 具有使用 URLSession 调用端点的便捷方法。如果需要一些高级功能，我们建议实现 API 客户端。该客户端应封装此框架未提供的逻辑（例如，签署授权端点或符合 URLSessionDelegate）。

此包包含预定义的 Endpoint 协议。为了方便起见，像多部分上传、自动编码/解码等用例被分成各种协议。

Endpoint 协议具有空的主体。通常在 GET 端点中使用。
DataEndpoint 在主体中发送提供的数据。
UploadEndpoint 使用 InputStream 上传文件。
MultipartEndpoint 将主体部分组合到 InputStream 中，并将它们发送到服务器。主体部分由 MultipartBodyPart 结构表示，并在数组中提供给端点。
RequestEndpoint 具有可编码的请求，该请求使用 Server 实例的编码进行编码。

用法

定义 Web 服务 (server)

首先，我们需要定义我们的服务器。首选结构体，但不是必需的

struct HTTPBinServer: URLServer {
    let baseUri = URL(string: "http://httpbin.org/")!
    let urlSession = URLSession(configuration: .default)
}

如果我们想使用自定义格式，我们只需要添加我们的编码/解码配置

struct HTTPBinServer: URLServer {
    ...

    let decoding: Decoding = JSONDecoding { decoder in
        decoder.keyDecodingStrategy = .convertFromSnakeCase
    }
    let encoding: Encoding = JSONEncoding { encoder in
        encoder.keyEncodingStrategy = .convertToSnakeCase
    }
}

如果我们需要创建特定的请求，添加一些标头，通常是为了提供授权，我们可以覆盖默认的请求构建机制。

struct HTTPBinServer: URLServer {
    ...
    func buildRequest(endpoint: Endpoint) throws -> URLRequest {
        var request = try buildStandardRequest(endpoint: endpoint)
        request.addValue("MyApp/1.0.0", forHTTPHeaderField: "User-Agent")
        return request
    }
}

定义端点

最基本的 GET 端点可以使用 Endpoint 协议来实现，所有默认属性都是推断出来的。

struct GetEndpoint: Endpoint {
    let path = "get"
}

让我们看一个更复杂的例子，比如更新一些模型。我们需要提供可编码的请求和可解码的响应。

struct UpdateUserEndpoint: RequestResponseEndpoint {
    typealias Response = User

    let request: User
    let path = "user"
}

执行请求

当我们定义了服务器和端点后，我们可以调用 Web 服务

let server = HTTPBinServer()
let endpoint = UpdateUserEndpoint(request: user)
server.call(response: endpoint) { result in
    switch result {
    case .success(let updatedUser):
        ...
    case .failure(let error):
        ...
    }
}

贡献者

当前的维护者和主要贡献者是 Matěj Kašpar Jirásek, matej.jirasek@futured.app.

我们要感谢其他贡献者，即

许可证

FTAPIKit 在 MIT 许可证下可用。有关更多信息，请参见 LICENSE 文件。