sample_ios 0.2.0
| 测试已测试 | ✗ |
| 语言语言 | SwiftSwift |
| 许可证 | MIT |
| 发布上次发布 | 2017年7月 |
| SwiftSwift 版本 | 3.0 3.0 3.0 |
| SPM支持 SPM | ✗ |
由 abspr 维护。
| 依赖项 | |
| Alamofire | >= 0 |
| SwiftyJSON | >= 0 |
sample_ios 0.2.0
- 作者
- hossein abbaspoor
Alamofire 是一个用 Swift 编写的 HTTP 网络库。
特性
- [x] 连接请求/响应方法
- [x] URL/JSON/plist 参数编码
- [x] 上传文件/数据/流/多部分表单数据
- [x] 使用请求或恢复数据下载文件
- [x] 使用 URLCredential 进行身份验证
- [x] HTTP 响应验证
- [x] 使用进度传递带有进度的上传和下载进度闭包
- [x] cURL 命令输出
- [x] 动态调整和要求请求重试
- [x] TLS 密钥和公共密钥固定
- [x] 网络可达性
- [x] 完整的单元和集成测试覆盖率
- [x] 完整文档
组件库
为了使 Alamofire 专注于核心网络实现，Alamofire 软件基金会创建了额外的组件库，以向 Alamofire 生态系统带来更多功能。
-
AlamofireImage - 一个图像库，包括图像响应序列化程序、
UIImage和UIImageView扩展、自定义图像滤镜、自动清除的内存缓存和基于优先级的图像下载系统。 -
AlamofireNetworkActivityIndicator - 通过Alamofire控制iOS上网络活动指示器的可见性。它包含可配置的延迟定时器，有助于减轻闪烁，并支持非Alamofire管理的
URLSession实例。
要求
- iOS 8.0+ / macOS 10.10+ / tvOS 9.0+ / watchOS 2.0+
- Xcode 8.1, 8.2, 8.3, 和 9.0
- Swift 3.0, 3.1, 3.2, 和 4.0
迁移指南
通讯
- 如果您需要帮助，请使用 Stack Overflow。 (使用标签 'alamofire')
- 如果您想问一个一般性的问题，请使用 Stack Overflow。
- 如果您发现了一个错误，请提交一个问题报告。
- 如果您有一个功能请求，请提交一个问题报告。
- 如果您想做出贡献，请提交一个合并请求。
安装
Swift 包管理器
Swift 包管理器是一个用于自动化Swift代码分发的工具，集成到swift编译器中。目前处于早期开发阶段，但是Alamofire支持在支持的平台上使用。
一旦您设置了Swift包，添加Alamofire作为依赖项就像将其添加到您的Package.swift文件中的dependencies值一样简单。
dependencies: [
.Package(url: "https://github.com/Alamofire/Alamofire.git", majorVersion: 4)
]手动
如果您不想使用上述任何依赖项管理器，您可以将Alamofire手动集成到项目中。
嵌入式框架
-
打开终端，
cd进入您的顶级项目目录，并运行以下命令（如果您的项目未初始化为git仓库）$ git init
-
通过运行以下命令将Alamofire添加为git 子模块
$ git submodule add https://github.com/Alamofire/Alamofire.git
-
打开新的
Alamofire文件夹，将Alamofire.xcodeproj拖放到您的应用Xcode项目的项目导航器中。它应该位于您的应用蓝色项目图标下面嵌套。它是在所有其他Xcode组之上还是之下并不重要。
-
在项目导航器中选择
Alamofire.xcodeproj并验证部署目标与您的应用目标相匹配。 -
接下来，在项目导航器中选择您的应用项目（蓝色项目图标），导航到目标配置窗口，并在侧边栏的“目标”标题下选择应用目标。
-
在此窗口的选项卡栏中，打开“常规”面板。
-
在“嵌入式二进制”部分下单击
+按钮。 -
您将看到两个不同的
Alamofire.xcodeproj文件夹，每个文件夹中都有两个不同的版本，嵌套在Products文件夹中的Alamofire.framework中。您选择哪个
Products文件夹无关紧要，但您选择的Alamofire.framework的上下位置很重要。 -
对于iOS，选择上面的
Alamofire.framework，对于OS X，选择下面的一个。您可以通过检查项目的构建日志来验证您选择了哪一个。针对
Alamofire的构建目标将列为主机Alamofire iOS、Alamofire macOS、Alamofire tvOS或Alamofire watchOS。 -
这就完成了！
默认情况下，
Alamofire.framework将作为目标依赖项、链接框架和嵌入框架添加到复制文件构建阶段，这就是您在模拟器和设备上构建所需的所有内容。
使用方法
发起请求
import Alamofire
Alamofire.request("https://httpbin.org/get")响应处理
处理在 Alamofire 中制作的 Request 的 Response 需要将响应处理程序链接到 Request。
Alamofire.request("https://httpbin.org/get").responseJSON { response in
print("Request: \(String(describing: response.request))") // original url request
print("Response: \(String(describing: response.response))") // http url response
print("Result: \(response.result)") // response serialization result
if let json = response.result.value {
print("JSON: \(json)") // serialized json response
}
if let data = response.data, let utf8Text = String(data: data, encoding: .utf8) {
print("Data: \(utf8Text)") // original server data as UTF8 string
}
}在上面的示例中，将 responseJSON 处理程序附加到将被执行的 Request。而不是阻止执行等待来自服务器的响应，指明了闭包形式的一个回调来处理收到响应。请求的结果仅在响应闭包的范围内可用。任何依赖于响应或从服务器获得的数据的执行都必须在响应闭包中进行。
Alamofire 中的网络是 异步 进行的。对不了解此概念的程序员来说，异步编程可能是一个来源 frustration的原因，但这样做有非常好的理由。
Alamofire 默认包含五个不同的响应处理程序，包括
// Response Handler - Unserialized Response
func response(
queue: DispatchQueue?,
completionHandler: @escaping (DefaultDataResponse) -> Void)
-> Self
// Response Data Handler - Serialized into Data
func responseData(
queue: DispatchQueue?,
completionHandler: @escaping (DataResponse<Data>) -> Void)
-> Self
// Response String Handler - Serialized into String
func responseString(
queue: DispatchQueue?,
encoding: String.Encoding?,
completionHandler: @escaping (DataResponse<String>) -> Void)
-> Self
// Response JSON Handler - Serialized into Any
func responseJSON(
queue: DispatchQueue?,
completionHandler: @escaping (DataResponse<Any>) -> Void)
-> Self
// Response PropertyList (plist) Handler - Serialized into Any
func responsePropertyList(
queue: DispatchQueue?,
completionHandler: @escaping (DataResponse<Any>) -> Void))
-> Self这些响应处理程序不会对其从服务器收到的 HTTPURLResponse 执行任何验证。
例如，状态代码在的
400..<500和500..<600范围内的response status codes不会自动触发一个Error。Alamofire 使用 响应验证 级联方法来实现这一点。
响应处理程序
response 处理程序不会评估任何响应数据。它只是将来自 URL 会话代理的所有信息直接转发。它是 Alamofire 使用 cURL 执行 Request 的等效物。
Alamofire.request("https://httpbin.org/get").response { response in
print("Request: \(response.request)")
print("Response: \(response.response)")
print("Error: \(response.error)")
if let data = response.data, let utf8Text = String(data: data, encoding: .utf8) {
print("Data: \(utf8Text)")
}
}我们强烈建议您利用其他响应序列化器，利用
Response和Result类型。
响应数据处理程序
responseData 处理程序使用 responseDataSerializer（将服务器数据序列化为其他类型的对象）提取服务器返回的 Data。如果没有发生错误并且返回了 Data，则响应 Result 将为 .success，而 value 将为 Data 类型。
Alamofire.request("https://httpbin.org/get").responseData { response in
debugPrint("All Response Info: \(response)")
if let data = response.result.value, let utf8Text = String(data: data, encoding: .utf8) {
print("Data: \(utf8Text)")
}
}响应字符串处理程序
responseString 处理程序使用 responseStringSerializer 将服务器返回的 Data 转换为指定编码的 String。如果没有发生错误并且服务器数据成功序列化为 String，则响应 Result 将为 .success，而 value 将为 String。
Alamofire.request("https://httpbin.org/get").responseString { response in
print("Success: \(response.result.isSuccess)")
print("Response String: \(response.result.value)")
}如果没有指定编码，则 Alamofire 将使用来自服务器的
HTTPURLResponse中指定的文本编码。如果无法通过服务器响应确定文本编码，则默认为.isoLatin1。
响应 JSON 处理程序
responseJSON 处理器使用 responseJSONSerializer 将服务器返回的 Data 转换为指定的 JSONSerialization.ReadingOptions 的 Any 类型。如果没有发生错误并且服务器数据成功序列化为 JSON 对象，则响应 Result 将是 .success，并且 value 的类型将是 Any。
Alamofire.request("https://httpbin.org/get").responseJSON { response in
debugPrint(response)
if let json = response.result.value {
print("JSON: \(json)")
}
}所有 JSON 序列化都由
Foundation框架中的JSONSerializationAPI 处理。
链式响应处理器
响应处理器甚至可以链式调用。
Alamofire.request("https://httpbin.org/get")
.responseString { response in
print("Response String: \(response.result.value)")
}
.responseJSON { response in
print("Response JSON: \(response.result.value)")
}需要注意的是，使用多个响应处理器在同一
Request上需要服务器数据被序列化多次。每次调用一个响应处理器。
响应处理器队列
默认情况下，响应处理器在主 dispatch 队列上执行。但是，可以提供自定义的 dispatch 队列。
let utilityQueue = DispatchQueue.global(qos: .utility)
Alamofire.request("https://httpbin.org/get").responseJSON(queue: utilityQueue) { response in
print("Executing response handler on utility queue")
}响应验证
默认情况下，Alamofire 将任何完成的请求视为成功，无论响应内容如何。在响应处理器之前调用 validate 会生成错误，如果响应有不可接受的状态代码或 MIME 类型。
手动验证
Alamofire.request("https://httpbin.org/get")
.validate(statusCode: 200..<300)
.validate(contentType: ["application/json"])
.responseData { response in
switch response.result {
case .success:
print("Validation Successful")
case .failure(let error):
print(error)
}
}自动验证
自动验证位于 200..<300 范围内的状态代码，并且响应的 Content-Type 响应头与请求的 Accept 响应头匹配（如果提供）。
Alamofire.request("https://httpbin.org/get").validate().responseJSON { response in
switch response.result {
case .success:
print("Validation Successful")
case .failure(let error):
print(error)
}
}响应缓存
响应缓存由系统框架级别的 URLCache 处理。它提供内存和磁盘的组合缓存，并允许您操作内存和磁盘部分的大小。
默认情况下，Alamofire 利用共享的
URLCache。要自定义它，请参阅 会话管理器配置 部分。
HTTP 方法
HTTPMethod 枚举列出 RFC 7231 §4.3 中定义的 HTTP 方法。
public enum HTTPMethod: String {
case options = "OPTIONS"
case get = "GET"
case head = "HEAD"
case post = "POST"
case put = "PUT"
case patch = "PATCH"
case delete = "DELETE"
case trace = "TRACE"
case connect = "CONNECT"
}这些值可以作为 method 参数传递给 Alamofire.request API。
Alamofire.request("https://httpbin.org/get") // method defaults to `.get`
Alamofire.request("https://httpbin.org/post", method: .post)
Alamofire.request("https://httpbin.org/put", method: .put)
Alamofire.request("https://httpbin.org/delete", method: .delete)
Alamofire.request方法参数默认为.get。
参数编码
Alamofire 支持 URL、JSON 和 PropertyList 三种类型的参数编码。它还可以支持任何符合 ParameterEncoding 协议的定制编码。
URL 编码
URLEncoding 类型创建一个 url 编码查询字符串，用于设置或附加到任何现有的 URL 查询字符串或设置为 URL 请求的 HTTP 主体。查询字符串是设置为或附加到任何现有 URL 查询字符串，还是设置为 HTTP 主体，取决于编码的 Destination。该 Destination 枚举有三个情况：
-
.methodDependent- 将编码查询字符串结果应用于GET、HEAD和DELETE请求的现有查询字符串，并将作为任何其他 HTTP 请求的 HTTP 主体设置。 -
.queryString- 将编码查询字符串结果设置为现有查询字符串或附加到查询字符串。 -
.httpBody- 将对查询字符串结果的编码设置为URL请求的HTTP主体。
带有HTTP主体的编码请求的Content-Type HTTP头字段设置为application/x-www-form-urlencoded; charset=utf-8。由于没有发布关于如何对集合类型进行编码的规范，习惯上是在数组值的键后面附加[]（如foo[]=1&foo[]=2），以及对嵌套字典值使用括号包围键（如foo[bar]=baz）。
带URL编码参数的GET请求
let parameters: Parameters = ["foo": "bar"]
// All three of these calls are equivalent
Alamofire.request("https://httpbin.org/get", parameters: parameters) // encoding defaults to `URLEncoding.default`
Alamofire.request("https://httpbin.org/get", parameters: parameters, encoding: URLEncoding.default)
Alamofire.request("https://httpbin.org/get", parameters: parameters, encoding: URLEncoding(destination: .methodDependent))
// https://httpbin.org/get?foo=bar带URL编码参数的POST请求
let parameters: Parameters = [
"foo": "bar",
"baz": ["a", 1],
"qux": [
"x": 1,
"y": 2,
"z": 3
]
]
// All three of these calls are equivalent
Alamofire.request("https://httpbin.org/post", method: .post, parameters: parameters)
Alamofire.request("https://httpbin.org/post", method: .post, parameters: parameters, encoding: URLEncoding.default)
Alamofire.request("https://httpbin.org/post", method: .post, parameters: parameters, encoding: URLEncoding.httpBody)
// HTTP body: foo=bar&baz[]=a&baz[]=1&qux[x]=1&qux[y]=2&qux[z]=3JSON编码
`JSONEncoding`类型创建参数对象的JSON表示，将其设置为请求的HTTP主体。编码请求的Content-Type HTTP头字段设置为application/json。
带JSON编码参数的POST请求
let parameters: Parameters = [
"foo": [1,2,3],
"bar": [
"baz": "qux"
]
]
// Both calls are equivalent
Alamofire.request("https://httpbin.org/post", method: .post, parameters: parameters, encoding: JSONEncoding.default)
Alamofire.request("https://httpbin.org/post", method: .post, parameters: parameters, encoding: JSONEncoding(options: []))
// HTTP body: {"foo": [1, 2, 3], "bar": {"baz": "qux"}}属性列表编码
`PropertyListEncoding`使用`PropertyListSerialization`根据关联的格式和写选项值创建参数对象的plist表示，将其设置为请求的主体。编码请求的`Content-Type` HTTP头字段设置为`application/x-plist`。
自定义编码
如果提供的`ParameterEncoding`类型不能满足您的需求，您可以创建自己的自定义编码。以下是一个创建自定义`JSONStringArrayEncoding`类型的快速示例，以便将JSON字符串数组编码到`Request`中。
struct JSONStringArrayEncoding: ParameterEncoding {
private let array: [String]
init(array: [String]) {
self.array = array
}
func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest {
var urlRequest = try urlRequest.asURLRequest()
let data = try JSONSerialization.data(withJSONObject: array, options: [])
if urlRequest.value(forHTTPHeaderField: "Content-Type") == nil {
urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
}
urlRequest.httpBody = data
return urlRequest
}
}手动编码URLRequest的参数
`ParameterEncoding` API可以在不做网络请求的情况下使用。
let url = URL(string: "https://httpbin.org/get")!
var urlRequest = URLRequest(url: url)
let parameters: Parameters = ["foo": "bar"]
let encodedURLRequest = try URLEncoding.queryString.encode(urlRequest, with: parameters)HTTP头
支持直接在全局`request`方法中添加自定义HTTP头到`Request`。这使得很容易将可经常更改的HTTP头附加到`Request`。
let headers: HTTPHeaders = [
"Authorization": "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
"Accept": "application/json"
]
Alamofire.request("https://httpbin.org/headers", headers: headers).responseJSON { response in
debugPrint(response)
}对于不更改的HTTP头，建议在`URLSessionConfiguration`上设置它们，从而使它们自动应用到由底层`URLSession`创建的任何`URLSessionTask`。有关更多信息，请参阅会话管理器配置部分。
默认的Alamofire `SessionManager`为每个`Request`提供了一个默认的HTTP头集合。这包括
-
Accept-Encoding，默认为`gzip;q=1.0, compress;q=0.5`，根据RFC 7230 §4.2.3。 -
Accept-Language，默认为系统上最顶部6个首选语言，格式为`en;q=1.0`，根据RFC 7231 §5.3.5。 -
User-Agent，包含有关当前应用版本的信息。例如：`iOS Example/1.0 (com.alamofire.iOS-Example; build:1; iOS 10.0.0) Alamofire/4.0.0`，根据RFC 7231 §5.5.3。
如果您需要自定义这些首部，则应创建一个自定义的 URLSessionConfiguration，更新 defaultHTTPHeaders 属性，并将配置应用于新的 SessionManager 实例。
身份验证
身份验证由系统框架级别的 URLCredential 和 URLAuthenticationChallenge 来处理。
支持的认证方案
HTTP Basic 认证
当适当的时，Request 的 authenticate 方法将自动向 URLAuthenticationChallenge 提供一个 URLCredential。
let user = "user"
let password = "password"
Alamofire.request("https://httpbin.org/basic-auth/\(user)/\(password)")
.authenticate(user: user, password: password)
.responseJSON { response in
debugPrint(response)
}根据您服务器的实现，可能还需要一个 Authorization 首部。
let user = "user"
let password = "password"
var headers: HTTPHeaders = [:]
if let authorizationHeader = Request.authorizationHeader(user: user, password: password) {
headers[authorizationHeader.key] = authorizationHeader.value
}
Alamofire.request("https://httpbin.org/basic-auth/user/password", headers: headers)
.responseJSON { response in
debugPrint(response)
}使用 URLCredential 进行身份验证
let user = "user"
let password = "password"
let credential = URLCredential(user: user, password: password, persistence: .forSession)
Alamofire.request("https://httpbin.org/basic-auth/\(user)/\(password)")
.authenticate(usingCredential: credential)
.responseJSON { response in
debugPrint(response)
}请注意，当使用
URLCredential进行身份验证时，如果服务器发出挑战，底层的URLSession实际上将发出两个请求。第一个请求将不包括凭证，这可能触发服务器的挑战。然后接收到挑战，附加凭证，并重试请求。
将数据下载到文件中
使用 Alamofire 请求从服务器获取数据时，可以在内存中或磁盘上下载数据。到目前为止的所有示例中使用的 Alamofire.request API 总是将服务器数据下载到内存中。这对于小型负载来说非常高效，但对于大型负载来说则很糟糕，因为下载可能会耗尽您的整个应用程序的内存。因此，您还可以使用 Alamofire.download API 将服务器数据下载到磁盘上的临时文件。
这仅适用于
macOS。其他平台不允许在您的应用程序沙盒之外访问文件系统。有关在其他平台上下载文件的信息，请参阅“下载文件目标”部分。
Alamofire.download("https://httpbin.org/image/png").responseData { response in
if let data = response.result.value {
let image = UIImage(data: data)
}
}如果需要您的应用程序在后台时下载数据，也应使用
Alamofire.downloadAPI。有关更多信息，请参阅“会话管理器配置”部分。
下载文件目标
您还可以提供一个 DownloadFileDestination 闭包，将文件从临时目录移动到最终目标。在将临时文件实际移动到 destinationURL 之前，将执行闭包中指定的 DownloadOptions。目前支持的 DownloadOptions 包含：
-
.createIntermediateDirectories- 如果指定，则为目标 URL 创建中间目录。 -
.removePreviousFile- 如果指定，从目标 URL 删除之前的文件。
let destination: DownloadRequest.DownloadFileDestination = { _, _ in
let documentsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
let fileURL = documentsURL.appendingPathComponent("pig.png")
return (fileURL, [.removePreviousFile, .createIntermediateDirectories])
}
Alamofire.download(urlString, to: destination).response { response in
print(response)
if response.error == nil, let imagePath = response.destinationURL?.path {
let image = UIImage(contentsOfFile: imagePath)
}
}您还可以使用建议的下载目标 API。
let destination = DownloadRequest.suggestedDownloadDestination(for: .documentDirectory)
Alamofire.download("https://httpbin.org/image/png", to: destination)下载进度
很多时候，向用户报告下载进度是有帮助的。任何 DownloadRequest 都可以使用 downloadProgress API 报告下载进度。
Alamofire.download("https://httpbin.org/image/png")
.downloadProgress { progress in
print("Download Progress: \(progress.fractionCompleted)")
}
.responseData { response in
if let data = response.result.value {
let image = UIImage(data: data)
}
}downloadProgress API 还接受一个 queue 参数，它定义了在哪个 DispatchQueue 上调用下载进度闭包。
let utilityQueue = DispatchQueue.global(qos: .utility)
Alamofire.download("https://httpbin.org/image/png")
.downloadProgress(queue: utilityQueue) { progress in
print("Download Progress: \(progress.fractionCompleted)")
}
.responseData { response in
if let data = response.result.value {
let image = UIImage(data: data)
}
}恢复下载
如果在执行过程中取消了或中断了 DownloadRequest，则底层的URL会话可能为活跃的 DownloadRequest 生成恢复数据。如果发生这种情况，可以重新使用恢复数据从上次停止的地方重新启动 DownloadRequest。可以通过下载响应访问恢复数据，并在尝试重新启动请求时重新使用。
重要： 在所有Apple平台的最新版本（iOS 10、macOS 10.12、tvOS 10、watchOS 3）上，
resumeData在背景URL会话配置中出现问题。在resumeData生成逻辑中存在一个底层错误，数据写入错误并且总是无法断点续传。有关错误和可能的解决方案的更多信息，请参阅此Stack Overflow 帖子。
class ImageRequestor {
private var resumeData: Data?
private var image: UIImage?
func fetchImage(completion: (UIImage?) -> Void) {
guard image == nil else { completion(image) ; return }
let destination: DownloadRequest.DownloadFileDestination = { _, _ in
let documentsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
let fileURL = documentsURL.appendingPathComponent("pig.png")
return (fileURL, [.removePreviousFile, .createIntermediateDirectories])
}
let request: DownloadRequest
if let resumeData = resumeData {
request = Alamofire.download(resumingWith: resumeData)
} else {
request = Alamofire.download("https://httpbin.org/image/png")
}
request.responseData { response in
switch response.result {
case .success(let data):
self.image = UIImage(data: data)
case .failure:
self.resumeData = response.resumeData
}
}
}
}将数据上传到服务器
当使用JSON或URL编码参数发送相对较小的数据量到服务器时，通常可以使用 Alamofire.request API。如果您需要从文件URL或 InputStream 发送大量数据，则应使用 Alamofire.upload API。
如果您需要在应用程序处于后台时上传数据，也应使用
Alamofire.uploadAPI。有关更多信息，请参阅会话管理器配置部分。
数据上传
let imageData = UIPNGRepresentation(image)!
Alamofire.upload(imageData, to: "https://httpbin.org/post").responseJSON { response in
debugPrint(response)
}上传文件
let fileURL = Bundle.main.url(forResource: "video", withExtension: "mov")
Alamofire.upload(fileURL, to: "https://httpbin.org/post").responseJSON { response in
debugPrint(response)
}上传表单数据
Alamofire.upload(
multipartFormData: { multipartFormData in
multipartFormData.append(unicornImageURL, withName: "unicorn")
multipartFormData.append(rainbowImageURL, withName: "rainbow")
},
to: "https://httpbin.org/post",
encodingCompletion: { encodingResult in
switch encodingResult {
case .success(let upload, _, _):
upload.responseJSON { response in
debugPrint(response)
}
case .failure(let encodingError):
print(encodingError)
}
}
)上传进度
当用户等待上传完成时，有时可以很方便地向用户显示上传进度。任何 UploadRequest 都可以使用 uploadProgress 和 downloadProgress API 报告上传进度和响应数据的下载进度。
let fileURL = Bundle.main.url(forResource: "video", withExtension: "mov")
Alamofire.upload(fileURL, to: "https://httpbin.org/post")
.uploadProgress { progress in // main queue by default
print("Upload Progress: \(progress.fractionCompleted)")
}
.downloadProgress { progress in // main queue by default
print("Download Progress: \(progress.fractionCompleted)")
}
.responseJSON { response in
debugPrint(response)
}统计指标
时间线
Alamofire在请求的生命周期中收集定时信息，创建一个 Timeline 对象，作为所有响应类型的属性公开。
Alamofire.request("https://httpbin.org/get").responseJSON { response in
print(response.timeline)
}以下报告以下 Timeline 信息
-
延迟：0.428秒 -
请求持续时间：0.428秒 -
序列化持续时间：0.001秒 -
总持续时间：0.429秒
URL会话任务指标
在iOS和tvOS 10以及macOS 10.12中，Apple引入了新的 URLSessionTaskMetrics API。任务指标封装了有关请求和响应执行的某些出色的统计信息。该API与 Timeline 非常相似，但提供了更多统计信息，这些信息Alamofire无法计算。可以通过任何响应类型访问这些指标。
Alamofire.request("https://httpbin.org/get").responseJSON { response in
print(response.metrics)
}值得注意的是，这些API仅在iOS、tvOS 10和macOS 10.12上可用。因此，根据您的部署目标，您可能需要在可用性检查中这些API。
Alamofire.request("https://httpbin.org/get").responseJSON { response in
if #available(iOS 10.0, *) {
print(response.metrics)
}
}cURL命令输出
调试平台问题可能会让人感到沮丧。幸运的是，Alamofire 的 Request 对象都遵循了 CustomStringConvertible 和 CustomDebugStringConvertible 协议，提供了一些非常有助于调试的工具。
CustomStringConvertible
let request = Alamofire.request("https://httpbin.org/ip")
print(request)
// GET https://httpbin.org/ip (200)CustomDebugStringConvertible
let request = Alamofire.request("https://httpbin.org/get", parameters: ["foo": "bar"])
debugPrint(request)输出
$ curl -i \
-H "User-Agent: Alamofire/4.0.0" \
-H "Accept-Encoding: gzip;q=1.0, compress;q=0.5" \
-H "Accept-Language: en;q=1.0,fr;q=0.9,de;q=0.8,zh-Hans;q=0.7,zh-Hant;q=0.6,ja;q=0.5" \
"https://httpbin.org/get?foo=bar"高级用法
Alamofire 构建于 URLSession 和 Foundation 的 URL 加载系统之上。为了充分利用这个框架，建议您熟悉底层网络堆栈的概念和功能。
推荐阅读
会话管理器
顶级便利方法，如 Alamofire.request，使用了 Alamofire.SessionManager 的默认实例，它配置了默认的 URLSessionConfiguration。
因此，以下两个语句等价：
Alamofire.request("https://httpbin.org/get")let sessionManager = Alamofire.SessionManager.default
sessionManager.request("https://httpbin.org/get")应用程序可以创建用于后台和短暂会话的会话管理器，以及自定义默认会话配置的新管理器，例如用于默认标头（httpAdditionalHeaders）或超时间隔（timeoutIntervalForRequest）。
使用默认配置创建会话管理器
let configuration = URLSessionConfiguration.default
let sessionManager = Alamofire.SessionManager(configuration: configuration)使用后台配置创建会话管理器
let configuration = URLSessionConfiguration.background(withIdentifier: "com.example.app.background")
let sessionManager = Alamofire.SessionManager(configuration: configuration)使用短暂配置创建会话管理器
let configuration = URLSessionConfiguration.ephemeral
let sessionManager = Alamofire.SessionManager(configuration: configuration)修改会话配置
var defaultHeaders = Alamofire.SessionManager.defaultHTTPHeaders
defaultHeaders["DNT"] = "1 (Do Not Track Enabled)"
let configuration = URLSessionConfiguration.default
configuration.httpAdditionalHeaders = defaultHeaders
let sessionManager = Alamofire.SessionManager(configuration: configuration)此操作不推荐用于
Authorization或Content-Type标头。相反，使用顶层Alamofire.requestAPI 的headers参数，分别使用URLRequestConvertible和ParameterEncoding。
会话代理
默认情况下，Alamofire 的 SessionManager 实例会创建一个 SessionDelegate 对象来处理底层 URLSession 生成的各种类型的代理回调。每个代理方法实现处理了这些类型调用中最常见的使用案例，将这些类型调用抽象，从而使顶层 API 脱离复杂性。然而，高级用户可能会因为各种原因需要覆盖默认功能。
覆盖闭包
自定义 SessionDelegate 行为的第一种方式是通过使用覆盖闭包。每个闭包都允许您覆盖匹配的 SessionDelegate API 的实现，同时仍然使用默认实现的所有其他 API。这使得定制代理功能子集变得容易。以下是一些可用的覆盖闭包的示例。
/// Overrides default behavior for URLSessionDelegate method `urlSession(_:didReceive:completionHandler:)`.
open var sessionDidReceiveChallenge: ((URLSession, URLAuthenticationChallenge) -> (URLSession.AuthChallengeDisposition, URLCredential?))?
/// Overrides default behavior for URLSessionDelegate method `urlSessionDidFinishEvents(forBackgroundURLSession:)`.
open var sessionDidFinishEventsForBackgroundURLSession: ((URLSession) -> Void)?
/// Overrides default behavior for URLSessionTaskDelegate method `urlSession(_:task:willPerformHTTPRedirection:newRequest:completionHandler:)`.
open var taskWillPerformHTTPRedirection: ((URLSession, URLSessionTask, HTTPURLResponse, URLRequest) -> URLRequest?)?
/// Overrides default behavior for URLSessionDataDelegate method `urlSession(_:dataTask:willCacheResponse:completionHandler:)`.
open var dataTaskWillCacheResponse: ((URLSession, URLSessionDataTask, CachedURLResponse) -> CachedURLResponse?)?以下是如何使用 taskWillPerformHTTPRedirection 来避免跟随转发的任何 apple.com 域的简短示例。
let sessionManager = Alamofire.SessionManager(configuration: URLSessionConfiguration.default)
let delegate: Alamofire.SessionDelegate = sessionManager.delegate
delegate.taskWillPerformHTTPRedirection = { session, task, response, request in
var finalRequest = request
if
let originalRequest = task.originalRequest,
let urlString = originalRequest.url?.urlString,
urlString.contains("apple.com")
{
finalRequest = originalRequest
}
return finalRequest
}子类化
覆盖默认的SessionDelegate实现的方法之一是通过子类化。子类化允许您完全自定义API的行为，或者为API创建代理并继续使用默认实现。创建代理允许您记录事件、发出通知、提供预和后钩子实现等。以下是一个子类化SessionDelegate的简单示例，当发生重定向时记录一条消息。
class LoggingSessionDelegate: SessionDelegate {
override func urlSession(
_ session: URLSession,
task: URLSessionTask,
willPerformHTTPRedirection response: HTTPURLResponse,
newRequest request: URLRequest,
completionHandler: @escaping (URLRequest?) -> Void)
{
print("URLSession will perform HTTP redirection to request: \(request)")
super.urlSession(
session,
task: task,
willPerformHTTPRedirection: response,
newRequest: request,
completionHandler: completionHandler
)
}
}一般来说，默认实现或覆盖闭包应提供所需的功能。只有作为最后的手段才应使用子类化。
需要记住的是，子代代理（subdelegates）是在默认实现中初始化和销毁的。在子类化时请小心，以防止内存泄露。
请求
request、download、upload或stream方法的返回结果均是由DataRequest、DownloadRequest、UploadRequest和StreamRequest继承的，它们都继承自Request。所有的Request实例都是通过拥有会话管理器创建的，并且从不直接初始化。
每个子类有其特有方法，如authenticate、validate、responseJSON和uploadProgress，每个方法都返回调用实例，以方便方法链式调用。
请求可以被暂停、恢复和取消
-
suspend()：暂停底层任务和调度队列。 -
resume()：恢复底层任务和调度队列。如果拥有管理器没有将startRequestsImmediately设置为true，请求必须调用resume()才能启动。 -
cancel()：取消底层任务，产生一个错误，此错误传递给任何已注册的响应处理程序。
请求路由
随着应用的增大，在构建网络堆栈时采用通用模式是重要的。该设计的重要部分是如何路由请求。Alamofire的URLConvertible和URLRequestConvertible协议以及Router设计模式就是为了帮助解决这个问题。
URLConvertible
采用URLConvertible协议的类型可以用来构造URL，然后用来构造URL请求。默认情况下，String、URL和URLComponents符合URLConvertible协议，允许将它们中的任何一个作为url参数传递给request、upload和download方法。
let urlString = "https://httpbin.org/post"
Alamofire.request(urlString, method: .post)
let url = URL(string: urlString)!
Alamofire.request(url, method: .post)
let urlComponents = URLComponents(url: url, resolvingAgainstBaseURL: true)!
Alamofire.request(urlComponents, method: .post)与应用程序进行重大互动的应用程序应该鼓励自定义类型符合URLConvertible，作为一种将领域特定模型映射到服务器资源的便捷方式。
类型安全的路由
extension User: URLConvertible {
static let baseURLString = "https://example.com"
func asURL() throws -> URL {
let urlString = User.baseURLString + "/users/\(username)/"
return try urlString.asURL()
}
}let user = User(username: "mattt")
Alamofire.request(user) // https://example.com/users/matttURLRequestConvertible
采用URLRequestConvertible协议的类型可以用来构造URL请求。默认情况下，URLRequest符合URLRequestConvertible协议，允许它直接传递给request、upload和download方法（这是指定自定义HTTP体的一种推荐方法）。
let url = URL(string: "https://httpbin.org/post")!
var urlRequest = URLRequest(url: url)
urlRequest.httpMethod = "POST"
let parameters = ["foo": "bar"]
do {
urlRequest.httpBody = try JSONSerialization.data(withJSONObject: parameters, options: [])
} catch {
// No-op
}
urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
Alamofire.request(urlRequest)与应用程序进行重大互动的应用程序应该鼓励自定义类型符合URLRequestConvertible，以确保请求端点的连续性。该方法可以用来抽象服务器端的不一致性，并提供类型安全的路由，同时管理认证凭证和其他状态。
API 参数抽象
enum Router: URLRequestConvertible {
case search(query: String, page: Int)
static let baseURLString = "https://example.com"
static let perPage = 50
// MARK: URLRequestConvertible
func asURLRequest() throws -> URLRequest {
let result: (path: String, parameters: Parameters) = {
switch self {
case let .search(query, page) where page > 0:
return ("/search", ["q": query, "offset": Router.perPage * page])
case let .search(query, _):
return ("/search", ["q": query])
}
}()
let url = try Router.baseURLString.asURL()
let urlRequest = URLRequest(url: url.appendingPathComponent(result.path))
return try URLEncoding.default.encode(urlRequest, with: result.parameters)
}
}Alamofire.request(Router.search(query: "foo bar", page: 1)) // https://example.com/search?q=foo%20bar&offset=50CRUD 与授权
import Alamofire
enum Router: URLRequestConvertible {
case createUser(parameters: Parameters)
case readUser(username: String)
case updateUser(username: String, parameters: Parameters)
case destroyUser(username: String)
static let baseURLString = "https://example.com"
var method: HTTPMethod {
switch self {
case .createUser:
return .post
case .readUser:
return .get
case .updateUser:
return .put
case .destroyUser:
return .delete
}
}
var path: String {
switch self {
case .createUser:
return "/users"
case .readUser(let username):
return "/users/\(username)"
case .updateUser(let username, _):
return "/users/\(username)"
case .destroyUser(let username):
return "/users/\(username)"
}
}
// MARK: URLRequestConvertible
func asURLRequest() throws -> URLRequest {
let url = try Router.baseURLString.asURL()
var urlRequest = URLRequest(url: url.appendingPathComponent(path))
urlRequest.httpMethod = method.rawValue
switch self {
case .createUser(let parameters):
urlRequest = try URLEncoding.default.encode(urlRequest, with: parameters)
case .updateUser(_, let parameters):
urlRequest = try URLEncoding.default.encode(urlRequest, with: parameters)
default:
break
}
return urlRequest
}
}Alamofire.request(Router.readUser("mattt")) // GET https://example.com/users/mattt适配和重试请求
如今，大多数网络服务都存在某种身份验证系统。其中之一是 OAuth。这通常涉及生成一个访问令牌，授权应用程序或用户调用各种受支持的web服务。虽然创建这些原始访问令牌可能是繁重的，但在访问令牌过期并需要获取新令牌时可能更加复杂。需要考虑许多线程安全的问题。
RequestAdapter 和 RequestRetrier 协议被创建，使得为特定集网络服务创建线程安全身份验证系统变得更加容易。
RequestAdapter
RequestAdapter 协议允许在创建之前检查并适配在 SessionManager 上执行的每个 Request。使用适配器的一个非常具体的方法是在一定类型的身份验证背后请求中添加一个 Authorization 标头。
class AccessTokenAdapter: RequestAdapter {
private let accessToken: String
init(accessToken: String) {
self.accessToken = accessToken
}
func adapt(_ urlRequest: URLRequest) throws -> URLRequest {
var urlRequest = urlRequest
if let urlString = urlRequest.url?.absoluteString, urlString.hasPrefix("https://httpbin.org") {
urlRequest.setValue("Bearer " + accessToken, forHTTPHeaderField: "Authorization")
}
return urlRequest
}
}let sessionManager = SessionManager()
sessionManager.adapter = AccessTokenAdapter(accessToken: "1234")
sessionManager.request("https://httpbin.org/get")RequestRetrier
RequestRetrier 协议允许在执行过程中遇到 Error 的 Request 重新执行。当同时使用 RequestAdapter 和 RequestRetrier 协议时，可以为 OAuth1、OAuth2、Basic Auth 甚至指数退避重试策略创建凭证刷新系统。可能性是无限的。以下是一个实现 OAuth2 访问令牌刷新流程的示例。
免责声明：这不是一个全局的
OAuth2解决方案。它仅仅是一个示例，展示如何使用RequestAdapter与RequestRetrier结合来创建线程安全刷新系统。
重申一次，不要复制此示例代码并将其放入生产应用程序中。这只是一个示例。每个身份验证系统都必须针对特定的平台和身份验证类型进行定制。
class OAuth2Handler: RequestAdapter, RequestRetrier {
private typealias RefreshCompletion = (_ succeeded: Bool, _ accessToken: String?, _ refreshToken: String?) -> Void
private let sessionManager: SessionManager = {
let configuration = URLSessionConfiguration.default
configuration.httpAdditionalHeaders = SessionManager.defaultHTTPHeaders
return SessionManager(configuration: configuration)
}()
private let lock = NSLock()
private var clientID: String
private var baseURLString: String
private var accessToken: String
private var refreshToken: String
private var isRefreshing = false
private var requestsToRetry: [RequestRetryCompletion] = []
// MARK: - Initialization
public init(clientID: String, baseURLString: String, accessToken: String, refreshToken: String) {
self.clientID = clientID
self.baseURLString = baseURLString
self.accessToken = accessToken
self.refreshToken = refreshToken
}
// MARK: - RequestAdapter
func adapt(_ urlRequest: URLRequest) throws -> URLRequest {
if let urlString = urlRequest.url?.absoluteString, urlString.hasPrefix(baseURLString) {
var urlRequest = urlRequest
urlRequest.setValue("Bearer " + accessToken, forHTTPHeaderField: "Authorization")
return urlRequest
}
return urlRequest
}
// MARK: - RequestRetrier
func should(_ manager: SessionManager, retry request: Request, with error: Error, completion: @escaping RequestRetryCompletion) {
lock.lock() ; defer { lock.unlock() }
if let response = request.task?.response as? HTTPURLResponse, response.statusCode == 401 {
requestsToRetry.append(completion)
if !isRefreshing {
refreshTokens { [weak self] succeeded, accessToken, refreshToken in
guard let strongSelf = self else { return }
strongSelf.lock.lock() ; defer { strongSelf.lock.unlock() }
if let accessToken = accessToken, let refreshToken = refreshToken {
strongSelf.accessToken = accessToken
strongSelf.refreshToken = refreshToken
}
strongSelf.requestsToRetry.forEach { $0(succeeded, 0.0) }
strongSelf.requestsToRetry.removeAll()
}
}
} else {
completion(false, 0.0)
}
}
// MARK: - Private - Refresh Tokens
private func refreshTokens(completion: @escaping RefreshCompletion) {
guard !isRefreshing else { return }
isRefreshing = true
let urlString = "\(baseURLString)/oauth2/token"
let parameters: [String: Any] = [
"access_token": accessToken,
"refresh_token": refreshToken,
"client_id": clientID,
"grant_type": "refresh_token"
]
sessionManager.request(urlString, method: .post, parameters: parameters, encoding: JSONEncoding.default)
.responseJSON { [weak self] response in
guard let strongSelf = self else { return }
if
let json = response.result.value as? [String: Any],
let accessToken = json["access_token"] as? String,
let refreshToken = json["refresh_token"] as? String
{
completion(true, accessToken, refreshToken)
} else {
completion(false, nil, nil)
}
strongSelf.isRefreshing = false
}
}
}let baseURLString = "https://some.domain-behind-oauth2.com"
let oauthHandler = OAuth2Handler(
clientID: "12345678",
baseURLString: baseURLString,
accessToken: "abcd1234",
refreshToken: "ef56789a"
)
let sessionManager = SessionManager()
sessionManager.adapter = oauthHandler
sessionManager.retrier = oauthHandler
let urlString = "\(baseURLString)/some/endpoint"
sessionManager.request(urlString).validate().responseJSON { response in
debugPrint(response)
}一旦 OAuth2Handler 被用作 SessionManager 的 adapter 和 retrier，它将自动刷新访问令牌并按相同的顺序重试所有失败的请求以处理无效访问令牌错误。
如果您需要按创建的顺序执行，则可以按任务标识符对它们进行排序。
上面的示例仅检查了 401 响应码，这远不足以健壮，但它展示了如何检查无效访问令牌错误。在生产应用程序中，人们希望检查 realm 以及大多数情况下 www-authenticate 标头响应，尽管这取决于 OAuth2 实现。
另一个重要的注意事项是，此身份验证系统可以在多个会话管理器之间共享。例如，您可能需要为同一个集网络服务使用 default 和 ephemeral 会话配置。上面的示例允许同一个 oauthHandler 实例跨多个会话管理器共享，以管理单个刷新流程。
自定义响应序列化
Alamofire 提供了内置的数据、字符串、JSON 和属性列表响应序列化。
Alamofire.request(...).responseData { (resp: DataResponse<Data>) in ... }
Alamofire.request(...).responseString { (resp: DataResponse<String>) in ... }
Alamofire.request(...).responseJSON { (resp: DataResponse<Any>) in ... }
Alamofire.request(...).responsePropertyList { resp: DataResponse<Any>) in ... }这些响应包括反序列化的 值（数据、字符串、任意类型）或 错误（网络、验证错误），以及 元数据（URL请求、HTTP头、状态码，《指标》，...）。
您有几种方式来自定义所有这些响应元素
响应映射
响应映射是生成自定义响应的最简单方法。它会转换响应的值，同时保留错误和元数据。例如，您可以将JSON响应 DataResponse<Any> 转换为包含应用程序模型的响应，如 DataResponse<User>。您可以通过 DataResponse.map 方法执行响应映射
Alamofire.request("https://example.com/users/mattt").responseJSON { (response: DataResponse<Any>) in
let userResponse = response.map { json in
// We assume an existing User(json: Any) initializer
return User(json: json)
}
// Process userResponse, of type DataResponse<User>:
if let user = userResponse.value {
print("User: { username: \(user.username), name: \(user.name) }")
}
}当转换可能引发错误时，使用 flatMap 代替
Alamofire.request("https://example.com/users/mattt").responseJSON { response in
let userResponse = response.flatMap { json in
try User(json: json)
}
}响应映射非常适合您的自定义完成处理程序
@discardableResult
func loadUser(completionHandler: @escaping (DataResponse<User>) -> Void) -> Alamofire.DataRequest {
return Alamofire.request("https://example.com/users/mattt").responseJSON { response in
let userResponse = response.flatMap { json in
try User(json: json)
}
completionHandler(userResponse)
}
}
loadUser { response in
if let user = response.value {
print("User: { username: \(user.username), name: \(user.name) }")
}
}当 map/flatMap 闭包可能处理大量数据时，请确保您在主线程之外执行它
@discardableResult
func loadUser(completionHandler: @escaping (DataResponse<User>) -> Void) -> Alamofire.DataRequest {
let utilityQueue = DispatchQueue.global(qos: .utility)
return Alamofire.request("https://example.com/users/mattt").responseJSON(queue: utilityQueue) { response in
let userResponse = response.flatMap { json in
try User(json: json)
}
DispatchQueue.main.async {
completionHandler(userResponse)
}
}
}map 和 flatMap 也可用于 下载响应。
错误处理
在实现自定义响应序列化器或对象序列化方法之前，考虑如何处理可能发生的任何错误非常重要。有两大基本选项：以未修改的方式传递现有错误，在响应时进行处理；或者，将所有错误包装在您应用程序特定的 Error 类型中。
例如，这里有一个简单的 BackendError 枚举，它将用于后续示例
enum BackendError: Error {
case network(error: Error) // Capture any underlying Error from the URLSession API
case dataSerialization(error: Error)
case jsonSerialization(error: Error)
case xmlSerialization(error: Error)
case objectSerialization(reason: String)
}创建自定义响应序列化器
Alamofire 提供了内置的字符串、JSON 和属性列表响应序列化，但可以通过扩展 Alamofire.DataRequest 和/或 Alamofire.DownloadRequest 来添加其他序列化。
例如，以下是使用 Ono 的响应处理程序的实现方法
extension DataRequest {
static func xmlResponseSerializer() -> DataResponseSerializer<ONOXMLDocument> {
return DataResponseSerializer { request, response, data, error in
// Pass through any underlying URLSession error to the .network case.
guard error == nil else { return .failure(BackendError.network(error: error!)) }
// Use Alamofire's existing data serializer to extract the data, passing the error as nil, as it has
// already been handled.
let result = Request.serializeResponseData(response: response, data: data, error: nil)
guard case let .success(validData) = result else {
return .failure(BackendError.dataSerialization(error: result.error! as! AFError))
}
do {
let xml = try ONOXMLDocument(data: validData)
return .success(xml)
} catch {
return .failure(BackendError.xmlSerialization(error: error))
}
}
}
@discardableResult
func responseXMLDocument(
queue: DispatchQueue? = nil,
completionHandler: @escaping (DataResponse<ONOXMLDocument>) -> Void)
-> Self
{
return response(
queue: queue,
responseSerializer: DataRequest.xmlResponseSerializer(),
completionHandler: completionHandler
)
}
}通用响应对象序列化
泛型可以用于提供自动、类型安全的响应对象序列化。
protocol ResponseObjectSerializable {
init?(response: HTTPURLResponse, representation: Any)
}
extension DataRequest {
func responseObject<T: ResponseObjectSerializable>(
queue: DispatchQueue? = nil,
completionHandler: @escaping (DataResponse<T>) -> Void)
-> Self
{
let responseSerializer = DataResponseSerializer<T> { request, response, data, error in
guard error == nil else { return .failure(BackendError.network(error: error!)) }
let jsonResponseSerializer = DataRequest.jsonResponseSerializer(options: .allowFragments)
let result = jsonResponseSerializer.serializeResponse(request, response, data, nil)
guard case let .success(jsonObject) = result else {
return .failure(BackendError.jsonSerialization(error: result.error!))
}
guard let response = response, let responseObject = T(response: response, representation: jsonObject) else {
return .failure(BackendError.objectSerialization(reason: "JSON could not be serialized: \(jsonObject)"))
}
return .success(responseObject)
}
return response(queue: queue, responseSerializer: responseSerializer, completionHandler: completionHandler)
}
}struct User: ResponseObjectSerializable, CustomStringConvertible {
let username: String
let name: String
var description: String {
return "User: { username: \(username), name: \(name) }"
}
init?(response: HTTPURLResponse, representation: Any) {
guard
let username = response.url?.lastPathComponent,
let representation = representation as? [String: Any],
let name = representation["name"] as? String
else { return nil }
self.username = username
self.name = name
}
}Alamofire.request("https://example.com/users/mattt").responseObject { (response: DataResponse<User>) in
debugPrint(response)
if let user = response.result.value {
print("User: { username: \(user.username), name: \(user.name) }")
}
}同样，您也可以使用这种方式来处理返回对象集合表示的端点
protocol ResponseCollectionSerializable {
static func collection(from response: HTTPURLResponse, withRepresentation representation: Any) -> [Self]
}
extension ResponseCollectionSerializable where Self: ResponseObjectSerializable {
static func collection(from response: HTTPURLResponse, withRepresentation representation: Any) -> [Self] {
var collection: [Self] = []
if let representation = representation as? [[String: Any]] {
for itemRepresentation in representation {
if let item = Self(response: response, representation: itemRepresentation) {
collection.append(item)
}
}
}
return collection
}
}extension DataRequest {
@discardableResult
func responseCollection<T: ResponseCollectionSerializable>(
queue: DispatchQueue? = nil,
completionHandler: @escaping (DataResponse<[T]>) -> Void) -> Self
{
let responseSerializer = DataResponseSerializer<[T]> { request, response, data, error in
guard error == nil else { return .failure(BackendError.network(error: error!)) }
let jsonSerializer = DataRequest.jsonResponseSerializer(options: .allowFragments)
let result = jsonSerializer.serializeResponse(request, response, data, nil)
guard case let .success(jsonObject) = result else {
return .failure(BackendError.jsonSerialization(error: result.error!))
}
guard let response = response else {
let reason = "Response collection could not be serialized due to nil response."
return .failure(BackendError.objectSerialization(reason: reason))
}
return .success(T.collection(from: response, withRepresentation: jsonObject))
}
return response(responseSerializer: responseSerializer, completionHandler: completionHandler)
}
}struct User: ResponseObjectSerializable, ResponseCollectionSerializable, CustomStringConvertible {
let username: String
let name: String
var description: String {
return "User: { username: \(username), name: \(name) }"
}
init?(response: HTTPURLResponse, representation: Any) {
guard
let username = response.url?.lastPathComponent,
let representation = representation as? [String: Any],
let name = representation["name"] as? String
else { return nil }
self.username = username
self.name = name
}
}Alamofire.request("https://example.com/users").responseCollection { (response: DataResponse<[User]>) in
debugPrint(response)
if let users = response.result.value {
users.forEach { print("- \($0)") }
}
}安全
在与服务器和网络服务进行通信时使用安全的 HTTPS 连接是保护敏感数据的重要一步。默认情况下，Alamofire 将使用 Security 框架提供的内置验证评估服务器提供的证书链。虽然这保证了证书链有效，但它并不能防止中间人攻击（MITM）或其他潜在漏洞。为了减轻中间人攻击，处理敏感客户数据或财务信息的应用程序应使用 ServerTrustPolicy 提供的证书或公钥固定。
服务器信任策略
服务器信任枚举对通过安全 HTTPS 连接连接到服务器时通常由 URLAuthenticationChallenge 提供的服务器信任进行评估。
let serverTrustPolicy = ServerTrustPolicy.pinCertificates(
certificates: ServerTrustPolicy.certificates(),
validateCertificateChain: true,
validateHost: true
)有大量不同的服务器信任评估案例，让您完全控制验证过程
-
performDefaultEvaluation：使用默认服务器信任评估，同时允许您控制是否验证挑战提供的主机。 -
pinCertificates：使用固定证书来验证服务器信任。如果其中一个固定证书与服务器证书之一匹配，则认为服务器信任是有效的。 -
pinPublicKeys：使用固定公钥来验证服务器信任。如果其中一个固定公钥与服务器证书公钥之一匹配，则认为服务器信任是有效的。 -
disableEvaluation：禁用所有评估，这反过来总是认为任何服务器信任都是有效的。 -
customEvaluation：使用关联的闭包来评估服务器信任的有效性，从而完全控制验证过程。请谨慎使用。
服务器信任策略管理器
ServerTrustPolicyManager 负责将服务器信任策略与特定主机的内部映射存储。这使 Alamofire 能够针对不同的服务器信任策略评估每个主机。
let serverTrustPolicies: [String: ServerTrustPolicy] = [
"test.example.com": .pinCertificates(
certificates: ServerTrustPolicy.certificates(),
validateCertificateChain: true,
validateHost: true
),
"insecure.expired-apis.com": .disableEvaluation
]
let sessionManager = SessionManager(
serverTrustPolicyManager: ServerTrustPolicyManager(policies: serverTrustPolicies)
)请保留对新的
SessionManager实例的引用，否则当您的sessionManager被释放时，您的所有请求都将被取消。
这些服务器信任策略将导致以下行为
-
test.example.com总是使用带有证书链和启用主机验证的证书固定，因此需要满足以下条件才能允许 TLS 握手成功- 证书链必须是有效的。
- 证书链必须包含一个固定证书。
- 挑战主机必须与证书链的叶证书中的主机匹配。
-
insecure.expired-apis.com从不评估证书链，并始终允许 TLS 握手成功。 - 所有其他主机将使用 Apple 提供的默认评估。
对服务器信任策略管理器进行子类化
如果您发现自己需要更灵活的服务器信任策略匹配行为（即通配符域名），则子类化 ServerTrustPolicyManager 并使用自己的自定义实现覆盖 serverTrustPolicyForHost 方法。
class CustomServerTrustPolicyManager: ServerTrustPolicyManager {
override func serverTrustPolicy(forHost host: String) -> ServerTrustPolicy? {
var policy: ServerTrustPolicy?
// Implement your custom domain matching behavior...
return policy
}
}验证主机
.performDefaultEvaluation、.pinCertificates 和 .pinPublicKeys 服务器信任策略都接受一个 validateHost 参数。将值设置为 true 将导致服务器信任评估验证证书中的主机名是否与挑战中的主机名匹配。如果不匹配，评估将失败。将 validateHost 设置为 false 仍然会评估完整的证书链，但不会验证叶证书的主机名。
建议在生产环境中始终将
validateHost设置为true。
验证证书链
证书固定和公钥都有使用 validateCertificateChain 参数验证证书链的选项。通过将此值设置为 true，除了执行与固定证书或公钥的字节相等性检查外，还将评估完整的证书链。将值设置为 false 将跳过证书链验证，但仍会执行字节相等性检查。
在有些情况下，禁用证书链验证是有意义的。禁用验证最常见的情况是自签名证书和过期证书。在这两种情况下，评估总是会失败，但字节相等性检查仍将确保您从服务器收到预期的证书。
建议在生产环境中始终将
validateCertificateChain设置为true。
应用传输安全
随着iOS 9中应用传输安全（ATS）的加入，使用包含多个ServerTrustPolicy对象的自定义ServerTrustPolicyManager可能没有任何效果。如果您持续看到CFNetwork SSL握手失败 (-9806)错误，您可能遇到了这个问题。除非您在应用plist中配置ATS设置以禁用足够的功能，否则苹果的ATS系统会覆盖整个挑战系统，让您的应用能够评估服务器信任。
如果您遇到这个问题（使用自签名证书的概率很高），可以通过将以下内容添加到您的Info.plist中来解决这个问题。
<dict>
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>example.com</key>
<dict>
<key>NSExceptionAllowsInsecureHTTPLoads</key>
<true/>
<key>NSExceptionRequiresForwardSecrecy</key>
<false/>
<key>NSIncludesSubdomains</key>
<true/>
<!-- Optional: Specify minimum TLS version -->
<key>NSTemporaryExceptionMinimumTLSVersion</key>
<string>TLSv1.2</string>
</dict>
</dict>
</dict>
</dict>您是否需要将NSExceptionRequiresForwardSecrecy设置为NO取决于您的TLS连接是否使用允许的加密套件。在某些情况下，需要将其设置为NO。NSExceptionAllowsInsecureHTTPLoads必须设置为YES，以便让SessionDelegate能够接收挑战回调。一旦调用挑战回调，ServerTrustPolicyManager将接管服务器信任评估。如果您尝试连接到仅支持小于1.2版本的TLS的主机，您可能还需要指定NSTemporaryExceptionMinimumTLSVersion。
建议在生产环境中始终使用有效的证书。
网络可达性
NetworkReachabilityManager监听WWAN和WiFi网络接口的主机和地址的可达性变化。
let manager = NetworkReachabilityManager(host: "www.apple.com")
manager?.listener = { status in
print("Network Status Changed: \(status)")
}
manager?.startListening()请确保记住在上面的示例中保留
manager，否则不会报告状态变化。同时，请不要在host字符串中包含方案，否则可达性功能将无法正常工作。
使用网络可达性来决定接下来要做什么时，有些重要事项需要记住。
-
不要使用可达性来判断是否应该发送网络请求。
- 您应该始终发送它。
- 当可达性恢复时，使用事件来重试失败的网络请求。
- 尽管网络请求可能仍然失败，但这是一个重试它们的良好时机。
- 网络可达性状态可以用来确定为什么网络请求可能失败。
- 如果网络请求失败，告诉用户由于离线而不是更技术性的错误（例如“请求超时”）会导致网络请求失败更有用。
建议查看WWDC 2012第706场会议，“网络最佳实践”以了解更多信息。
Open Radars
以下radars对Alamofire的当前实现有一些影响。
-
rdar://21349340- 测试案例中的toll-free桥接问题导致的编译器发出警告 -
rdar://26761490- Swift字符串插值在常见使用中导致内存泄漏 -
rdar://26870455- 在模拟器中，后台URL会话配置不起作用 -
rdar://26849668- 一些URLProtocol API没有正确处理URLRequest
FAQ
Alamofire的命名来源是什么？
Alamofire的名字来源于Alamo Fire花，这是一种德克萨斯州州花蓝天绶草的杂交品种。
在路由器（Router）与请求适配器（Request Adapter）中应包含哪些逻辑？
简单、静态数据，例如路径、参数和通用标头应包含在 Router 中。动态数据，例如可以基于认证系统改变的 Authorization 标头应包含在 RequestAdapter 中。
动态数据必须放置到 RequestAdapter 中的原因是为了支持重试操作。当请求（Request）重试时，原始请求不会被重建，这意味着不会再次调用 Router。而是再次调用 RequestAdapter，以便在重试请求之前更新原始请求中的动态数据。
鸣谢
Alamofire 由 Alamofire 软件基金会 拥有和维护。您可以在推特上关注他们以获取项目更新和发布信息：@AlamofireSF。
安全披露
如果您认为您已经发现了一个与 Alamofire 相关的安全漏洞，请尽快通过电子邮件报告给 [email protected]。请勿公开发布到公共问题跟踪器。
捐赠
ASF 希望筹集资金以正式注册为一个联邦非营利组织。注册将使我们成员获得一些法律保护，并允许我们将捐赠用于免税。向 ASF 捐赠将使我们能够
- 支付注册为联邦非营利组织的法律费用
- 支付保持非营利组织良好状态的一年期法律费用
- 支付邮件服务器费用以帮助我们处理所有问题和安全问题
- 可能资助测试服务器以便我们更容易测试边界情况
- 可能资助开发人员全职地在我们项目上工作
ASF 库的社区采用度非常惊人。我们对您对项目的热情感到非常谦虚，并希望能够继续尽一切可能推进项目的进展。在您的持续支持下，ASF 将能够扩大其影响力，并为核心成员提供更好的法律保障。如果您在工作中使用我们的任何库，请看看您的雇主是否有兴趣进行捐赠。我们的初步目标是筹集 1000 美元，以整理所有法律事宜并启动此次活动。今天您能捐赠的任何金额都将被极大地欢迎。
许可
Alamofire 在 MIT 许可下发布。有关详细信息，请参阅 LICENSE。