FTAPIKit 1.5.0

FTAPIKit 1.5.0

×

由 Futured 维护。

FTAPIKit 1.5.0

FTAPIKit logo

FTAPIKit

Cocoapods Cocoapods platforms License

macOS 11 macOS 10.15 Ubuntu

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

安装

当使用 Swift 包管理器时，使用 Xcode 11+ 或将以下行添加到您的依赖项中

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

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

pod 'FTAPIKit', '~> 1.5'

功能

该库的主要功能是提供类似文档的 API 来定义网络服务。这是通过 Swift 中的声明式和协议导向编程实现的。

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

  • Server 协议定义单个网络服务。
  • Endpoint 协议定义资源的访问点。

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

Architecture

此包包含预定义的 Endpoint 协议。诸如多部分上传、自动编码/解码等用例在各个协议中分离，以方便使用。

  • Endpoint 协议没有主体。通常用于 GET 端点。
  • DataEndpoint 将提供的数据发送到主体中。
  • UploadEndpoint 使用 InputStream 上传文件。
  • MultipartEndpoint 将体部分合并为 InputStream 并将其发送到服务器。体部分由 MultipartBodyPart 结构体表示，并以数组的形式提供给端点。
  • RequestEndpoint 包含可编码的请求，该请求使用 Server 实例的编解码方式编码。

Endpoint types

使用方法

定义网络服务（服务器）

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

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"
}

执行请求

当服务器和端点定义后，我们可以调用网络服务。

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，[email protected]。

我们感谢其他贡献者，包括

许可证

FTAPIKit采用MIT许可。有关更多信息，请参阅LICENSE文件。