PinButton 0.1.1

您想在 Podfile 中添加以下内容，类似于下面的示例：

target 'MyApp' do
  pod 'PinButton', '~> 0.1'
end

然后在终端或从 CocoaPods.app 中运行 pod install。

或者为了进行测试，运行以下命令

pod try PinButton

PinButton 0.1.1

作者
Çağrı ÇOLAK

Alamofire 是一个用 Swift 编写的 HTTP 网络库。

功能
组件库
要求
迁移指南
沟通
安装
使用
- 简介 - 发起请求，响应处理，响应验证，响应缓存
- HTTP - HTTP 方法，参数编码，HTTP 头部，认证
- 大数据 - 将数据下载到文件，上传数据到服务器
- 工具 - 统计指标，cURL 命令输出
高级使用
- URL Session - 会话管理，会话代理，请求
- 路由 - 路由请求，调整和重试请求
- 模型对象 - 自定义响应序列化
- 连接 - 安全，网络可达性
公开的问题追踪
常见问题解答
鸣谢
捐助
许可证

功能

[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+
Swift 3.0+

迁移指南

联系方式

如果您需要帮助，请使用Stack Overflow。（标签 'alamofire'）
如果您想提问一个一般性问题，请使用Stack Overflow。
如果您发现了一个bug，请打开一个issue。
如果您有一个功能请求，请打开一个issue。
如果您想贡献，请提交一个pull request。

安装

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


- Add Alamofire as a git [submodule](https://git-scm.cn/docs/git-submodule) by running the following command:

  ```bash
$ git submodule add https://github.com/Alamofire/Alamofire.git

打开新的Alamofire文件夹，并将Alamofire.xcodeproj拖放到应用的Xcode项目的“项目导航器”中。

它应该嵌套在您的应用的蓝色项目图标下。它位于所有其他Xcode组之上或之下并不重要。
在“项目导航器”中选中Alamofire.xcodeproj，并验证部署目标与您的应用目标相匹配。
接下来，在“项目导航器”中（蓝色项目图标）选中您的大项目，导航到目标配置窗口，并在侧边栏的“目标”标题下选择应用目标。
在窗口顶部的选项卡栏中，打开“通用”面板。
在“内嵌框架”部分下单击+按钮。
您将看到两个不同的Alamofire.xcodeproj文件夹，每个文件夹中都包含位于“产品”文件夹内的两个不同版本的Alamofire.framework。

您选择哪个“产品”文件夹无关紧要，但您选择的是顶部的还是底部的Alamofire.framework则很重要。
选择iOS的顶部Alamofire.framework和OS X的底部Alamofire.framework。

您可以通过查看项目的构建日志来验证您选择了哪个选项。对于 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(response.request)  // original URL request
    print(response.response) // HTTP URL response
    print(response.data)     // server data
    print(response.result)   // result of response serialization

    if let JSON = response.result.value {
        print("JSON: \(JSON)")
    }
}

在上面的示例中，将 responseJSON 处理器附加到要执行的 Request 上，以便在 Request 完成（一旦收到响应）后执行。而不是阻止执行以等待从服务器接收响应，指定了一个作为闭包形式的回调来处理响应。请求的结果仅在响应闭包的作用域内可用。必须在响应闭包内完成任何依赖于响应或从服务器接收的数据的执行。

在 Alamofire 中进行网络操作是 异步的。异步编程可能是编程新手的不满之源，但这样做有非常好的原因。

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..<499 和 500..<599 范围内的响应不会自动触发错误。Alamofire 使用响应验证方法连接来实现这一点。

响应处理器

response 处理器不评估任何响应数据。它只是直接从 URL 会话代理传播所有信息。它相当于使用 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。如果没有发生任何错误并且返回了 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框架中的JSONSerialization API处理。

链式响应处理器

响应处理器甚至可以是链式的。

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上使用多个响应处理器需要将服务器数据序列化多次。每次序列化一次，对应一个响应处理器。

响应处理器队列

默认情况下，响应处理器在主调度队列上执行。但是，也可以提供自定义调度队列。

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类型 unacceptable 时生成错误。

手动验证

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...299范围内，并且响应的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 请求体。

具有请求体的编码请求的 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]=3

JSON 编码

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 = urlRequest.urlRequest

        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 方法中直接支持向 Request 添加自定义 HTTP 头部。这使得轻松地将 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 提供一组默认头。这包括

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基本认证

Request上的authenticate方法会根据需要自动提供URLCredential给URLAuthenticationChallenge。

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从服务器获取数据的请求可以将数据下载到内存中或者磁盘中。到目前为止的所有示例中使用的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.download API。有关更多信息，请参阅会话管理者配置部分。

下载文件目的地

您还可以提供一个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.appendPathComponent("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(directory: .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.appendPathComponent("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.upload API。有关更多信息，请参阅会话管理器配置部分。

上传数据

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 中可用。因此，根据您的部署目标，您可能需要在可用性检查中使用它们

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.request API 中使用 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/mattt

URLRequestConvertible

采用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=50

CRUD & 授权

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。这通常涉及生成访问令牌，授权应用程序或用户调用多种受支持的网络服务。虽然创建这些初始访问令牌可能相当费力，但当您的访问令牌过期并且需要获取新的访问令牌时，情况会更加复杂。需要考虑许多线程安全问题。

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、基本身份验证甚至指数退避重试策略的凭据刷新系统。可能性是无穷的。以下是一个实现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 ... }

这些响应包装了反序列化后的值（Data、String、Any）或错误（网络、验证错误），以及元数据（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 = userResponse.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)") }
    }
}

安全

在与服务器和Web服务通信时使用安全的HTTPS连接是保护敏感数据的重要步骤。默认情况下，Alamofire将使用Security框架内置的验证来评估服务器提供的证书链。虽然这保证了证书链有效，但它不能防止中间人攻击（MITM）或其他潜在的漏洞。为了减轻MITM攻击，处理敏感客户数据或财务信息的应用程序应使用 ServerTrustPolicy 提供的证书或公钥固定。

服务器信任策略

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 SSLHandshake failed (-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。为了使SessionDelegate能够接收挑战回调，NSExceptionällerowsInsecureHTTPLoads必须设置为YES。一旦开始调用挑战回调，ServerTrustPolicyManager将接管服务器信任评估。如果您正在尝试连接到仅支持TLS版本小于1.2的主机，您可能还需要指定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 Session 706，“网络最佳实践”以获取更多信息。

公开雷达

以下雷达对Alamofire当前实现有一定影响。

rdar://21349340 - 测试案例中由于免费用桥接问题导致的编译器警告
rdar://26761490 - Swift字符串插值在常见用法中导致内存泄漏
rdar://26870455 - 在模拟器中，背景URL会话配置不起作用
rdar://26849668 - 一些URLProtocol API未正确处理URLRequest

常见问题解答

Alamofire的名字的来源是什么？

Alamofire这个名字来源于Alamo Fire花，这是德克萨斯州官方州花的蓝铃的杂交品种。

在路由器与请求适配器之间应该放入哪些逻辑？

简单的静态数据，如路径、参数和常用头信息应当放在 Router 中。动态数据，比如基于认证系统的值的 Authorization 头信息，应该放在 RequestAdapter 中。

动态数据必须放在 RequestAdapter 中的原因是支持重试操作。当一个 Request 被重试时，原始请求不会被重建，这意味着不会再次调用 Router。这时会再次调用 RequestAdapter，以便在重试请求之前更新原始请求上的动态数据。

致谢

Alamofire 由 Alamofire 软件基金会所有并维护。您可以在 Twitter 上关注他们 @AlamofireSF，以获取项目更新和发布信息。

安全披露

如果您认为您已经识别出 Alamofire 的安全漏洞，请尽快通过电子邮件[email protected] 报告。请不要将其发布到公共问题跟踪器。

捐赠

ASF 正在寻找筹款以正式注册为一个联邦的非营利组织。注册将允许我们成员获得某些法律保护，并允许我们免税使用捐款。向 ASF 捐赠将使我们能够

支付作为联邦非营利组织注册的法律费用
支付保持非营利组织良好状态的年度法律费用
支付我们的邮件服务器费用，帮助我们跟踪所有问题和安全漏洞
可能为测试服务器提供资金，以使我们更容易测试边缘情况
可能为开发者提供资金，让他们全职参与我们的某个项目

ASF 库的社区采用已经非常令人瞩目。我们对你们对项目的热情感到非常谦卑，并希望尽我们所能继续推动项目进步。有了您的持续支持，ASF 将能够提高其辐射范围，并为核心成员提供更好的法律保障。如果您在工作中使用任何我们的库，看看您的雇主是否对捐赠感兴趣。我们的初步目标是筹集 $1000，以便我们有条不紊地将所有法律事宜搞定并启动这项运动。任何您今天可以捐赠以帮助我们达成目标的钱都将被非常感激。

许可证

Alamofire 在 MIT 许可证下发布。详细信息请参阅 LICENSE。