简介

千位数是一个开源框架，用于在iOS和tvOS中消费REST服务。项目名称来源于航海标志的K或Kilo，意味着“我希望与你通话”

本指南介绍了Kilo框架并概述了其关键特性。

内容

获取Kilo
WebServiceProxy
更多信息

获取Kilo

千位数作为一个通用的二进制文件进行分发，它不仅可以在iOS模拟器上运行，还可以在真正的设备上运行。同时，它也通过CocoaPods提供。需要iOS 11或tvOS 11或更高版本。

要安装

下载最新版本存档并展开
在Xcode中，在项目导航器视图中选择项目根节点
选择应用程序目标
选择“通用”选项卡
将Kilo.framework拖到“嵌入的二进制文件”部分
在出现的对话框中，确保选中“如果需要则复制项目”，然后点击“完成”

注意，在提交到App Store之前，框架二进制文件必须“修剪”。有关更多信息，请参阅部署部分。

WebServiceProxy

WebServiceProxy 类用于向服务器发送 API 请求。此类提供单个初始化器，该初始化器接受以下参数：

session - 一个 URLSession 实例
serviceURL -服务的基 URL

服务操作通过以下方法之一启动：

public func invoke(_ method: Method, path: String,
    arguments: [String: Any] = [:],
    content: Data? = nil, contentType: String? = nil,
    resultHandler: @escaping ResultHandler<Void>) -> URLSessionDataTask? { ... }

public func invoke<T: Decodable>(_ method: Method, path: String,
    arguments: [String: Any] = [:],
    content: Data? = nil, contentType: String? = nil,
    resultHandler: @escaping ResultHandler<T>) -> URLSessionDataTask? { ... }

public func invoke<T>(_ method: Method, path: String,
    arguments: [String: Any] = [:],
    content: Data? = nil, contentType: String? = nil,
    responseHandler: @escaping ResponseHandler<T>,
    resultHandler: @escaping ResultHandler<T>) -> URLSessionDataTask? { ... }

所有三种变体都接受以下参数：

method - 要执行的 HTTP 方法
path - 请求资源的路径，相对于服务 URL
arguments - 一个字典，包含方法参数作为键值对
content - 可选的表示请求主体的 Data 实例
contentType - 可选的字符串值，包含内容的 MIME 类型
resultHandler - 一个回调，在请求完成后将被调用

第一个版本执行不返回值的服务的操作。第二个使用 JSONDecoder 反序列化响应，具有 millisecondsSince1970 的日期解码策略。第三个版本接受额外的 responseHandler 参数，以方便自定义响应内容的解码（例如，UIImage）。

响应和结果处理程序回调如下定义：

public typealias ResponseHandler<T> = (_ content: Data, _ contentType: String?, _ headers: [String: String]) throws -> T

public typealias ResultHandler<T> = (_ result: Result<T, Error>) -> Void

所有三种方法返回一个表示调用请求的 URLSessionDataTask 实例。这允许应用程序监视悬而未决的请求的状态或在需要时取消请求。

参数

与 HTML 表单类似，参数可以通过查询字符串或请求体提交。对于 GET、PUT 和 DELETE 请求的参数始终在查询字符串中发送。POST 参数通常在请求体中发送，可以提交为 "application/x-www-form-urlencoded" 或 "multipart/form-data"（由服务代理的 encoding 属性确定）。但是，如果通过 content 参数指定了自定义体，则 POST 参数将发送在查询字符串中。

任何值都可以用作参数。但是，忽略 NSNull 值，并将 Date 实例转换为表示纪元时间的 64 位整数值（自 1970 年 1 月 1 日午夜以来的毫秒数）。

此外，数组实例表示多值参数，其行为类似于 HTML 中的 <select multiple> 标签。此外，在启用多部分表单数据编码时，URL 实例表示文件上传，并且在 HTML 表单中类似于 <input type="file"> 标签。URL 值的数组在操作上类似于 <input type="file" multiple> 标签。

返回值

在操作完成后调用结果处理程序。如果成功，第一个参数将包含服务器返回内容的反序列化表示，第二个参数将是 nil。否则，第一个参数将是 nil，第二个将填充一个描述发生的问题的 Error 实例。

如果服务返回一个内容类型为 "text/plain" 的错误响应，则错误描述中将提供错误主体的信息。

线程考虑事项

虽然服务请求通常在后台线程上处理，但结果处理器始终在应用程序的主线程上执行。这允许结果处理器直接更新用户界面，而不是向主队列中发送单独的更新操作。请注意，响应处理器在调用结果处理器之前在后台执行。

示例

以下Swift代码展示了如何使用WebServiceProxy类访问返回斐波那契数列前n个值的服务的例子

let webServiceProxy = WebServiceProxy(session: URLSession.shared, serviceURL: serviceURL)

// GET test/fibonacci?count=8
webServiceProxy.invoke(.get, path: "test/fibonacci", arguments: [
    "count": 8
]) { [weak self] (result: Result<[Int], Error>) in
    // [0, 1, 1, 2, 3, 5, 8, 13]
}

部署

在提交到App Store之前，Kilo框架必须进行“修剪”。

将trim.sh脚本放在你的项目根目录中
确保脚本具有执行权限（例如：744）
在“嵌入框架”阶段之后创建一个新的“运行脚本”构建阶段
将新的构建阶段重命名为“修剪框架可执行文件”或类似名称（可选）
调用脚本（例如："${SRCROOT}/trim.sh" Kilo）

附加信息

本指南介绍了Kilo框架，并提供了其核心功能的概述。有关更多信息，请参阅示例。

千位 1.3.2

千位 1.3.2

千位 1.3.2

简介

内容

获取Kilo

WebServiceProxy

参数

返回值

线程考虑事项

示例

部署

附加信息