APIota

APIota 是一个轻量级的 Swift 库，用于定义 iOS、macOS、tvOS、watchOS 或 Linux 中使用的 API 客户端。它采用面向协议的方法编写，并且可以非常轻松地从 JSON REST API 端点解码您的 Codable 模型对象！

支持的平台
特性
安装
用法
报告错误和请求功能
功能路线图
许可证

支持的平台

iOS
macOS
tvOS
watchOS * (见下方注释)
Linux

注意

watchOS 支持可作为 APIota 库的用户使用。但是，由于 XCTest 在 watchOS 上不可用，因此目前直接从源代码构建会失败。

支持的 Swift 语言版本和构建工具

Swift 5.2 或更高版本
Xcode 11.4 或更高版本

特性

使用 Codable 模型对象时，支持 JSON 请求和响应正文的编码和解码。
- 可以通过提供配置好的 JSONEncoder 或 JSONDecoder 实例来自定义编码和解码策略。
支持 Combine (在针对 iOS 13.0+、macOS 10.15+、tvOS 13.0+ 或 watchOS 6.0+ 构建时)。
支持 URL 编码的表单数据请求。

安装

使用 Swift Package Manager

只需将以下内容添加到您的 Package.swift 文件中的 dependencies 数组中

dependencies: [
    …
    .package(url: "https://github.com/danielrbrowne/APIota", from: "0.2.0"),
    …
  ]

用法

在其核心，使用 APIota 定义 API 客户端非常简单。有两个协议，APIotaClient 和 APIotaCodableEndpoint，它们构成了库的基础。

第一步是定义一个对象，指定 REST API 的基本 URL（即 URLComponents 实例中的 host），您将与之通信。下面显示了一个示例

struct JSONPlaceholderAPIClient: APIotaClient {

    let session = URLSession.shared

    let decoder = JSONDecoder()

    var baseUrlComponents: URLComponents = {
        var components = URLComponents()
        components.host = "jsonplaceholder.typicode.com"
        components.scheme = "https"

        return components
    }()
}

下一步是定义应该发送请求的端点。下面显示了一个简单的 GET 请求的示例，但是也可以轻松定义更复杂的请求

struct JSONPlaceholderGetTodosEndpoint: APIotaCodableEndpoint {
    typealias SuccessResponse = [Todo]
    typealias ErrorResponse = MyDecodableError
    typealias Body = MyEncodableBody

    let headers: HTTPHeaders? = nil

    let httpBody: Body? = nil

    let httpMethod: HTTPMethod = .GET

    let path = "/todos"

    let queryItems: [URLQueryItem]? = nil
}

然后可以通过 Client 的实例将请求发送到 REST API，如下所示

…
private static let apiClient = TestAPIClient()
private(set) lazy var cancellable: AnyCancellable? = nil
private var todosList: [Todo] = []
…

// Example 1: API response returned via a callback closure

let endpoint = JSONPlaceholderGetTodosEndpoint()
Self.apiClient.sendRequest(for: endpoint) { result in
    // Handle the returned `Result<T.Response, Error>`
    switch result {
    case .success(let todosList):
        self.todosList = todosList
    case .failure(let error):
        // Handle the error returned from the API Client
    }
}

// Example 2: API response returned via a Combine publisher

let endpoint = JSONPlaceholderGetTodosEndpoint()
cancellable = Self.apiClient.sendRequest(for: endpoint)
    .catch({ error in
        // Handle the error returned from the API Client
    })
    .assign(to: \.todosList, on: self)
}

文档和参考

APIota 的完整文档可以在 API 文档中找到。

可以在示例项目中找到 APIota 实际应用的一个例子。

报告错误和请求功能

请确保在报告错误或请求新功能时使用相关的 issue 模板。并且请首先检查是否已经有 open issue 涵盖了您的错误报告或新功能请求。

功能路线图

没有特别的顺序，作为一个草案提案

自动推断请求的 Content-Type 标头。
可定制的请求参数编码策略。
可配置的请求响应缓存。
支持多部分表单数据。
可配置的请求重试。
请求身份验证质询处理。
全面的测试覆盖。
Cocoapods 支持。

许可证

APIota 是完全开源的，并根据 MIT 许可证发布。如果您想在自己的项目中使用它，请参阅 LICENSE.md 了解详细信息。