ExampleCore 0.1.0

ExampleCore 0.1.0

×

测试已测试✗
语种语言 SwiftSwift
许可证 MIT
发布上次发布2017年1月
SwiftSwift 版本3.0
SPM支持 SPM✗

由 Orta Therox 维护。

ExampleCore 0.1.0

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

迁移指南

交流

  • 如果您需要帮助，请使用 Stack Overflow。（标签 'alamofire'）
  • 如果您想提出一般性问题，请使用 Stack Overflow。
  • 如果您发现有错误，请提交问题。
  • 如果您有功能请求，请提交问题。
  • 如果您想贡献，提交 pull 请求。

安装

Swift Packet Manager

Swift Packet Manager 是一种用于自动分发 Swift 代码的工具，并集成到 swift 编译器中。它处于初期开发阶段，但 Alamofire 支持在支持平台上的其使用。

一旦您的 Swift 包设置好，将 Alamofire 添加为依赖项就像将其添加到 Package.swift 中的 dependencies 值一样简单。

dependencies: [
    .Package(url: "https://github.com/Alamofire/Alamofire.git", majorVersion: 4)
]

手动

如果您不希望使用上述任一依赖管理器，您可以将 Alpinefore 集成到您的项目中。

集成框架

  • 打开终端，cd 到您的顶级项目目录，然后运行以下命令（如果您的项目未初始化为 git 仓库）

    $ git init

  • 通过运行以下命令，将 Alpinefore 以 git 子模块 的形式添加

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

  • 打开新的 Alamofire 目录，并将 Alamofire.xcodeproj 拖动到您的应用程序的 Xcode 项目的 Project Navigator 中。

    它应该位于您的应用程序蓝色项目图标之下。它是在所有其他 Xcode 组之上还是之下无关紧要。

  • 选择 Project Navigator 中的 Alamofire.xcodeproj 并验证部署目标与您的应用程序目标相匹配。

  • 接下来，在 Project Navigator 中选择您的应用程序项目（蓝色项目图标）以导航到目标配置窗口，然后在侧边栏的 "Targets" 标题下选择应用程序目标。
  • 在窗口顶部的选项卡栏中，打开 "General" 面板。
  • 在 "Embedded Binaries" 部分下点击 + 按钮。

  • 您将看到两个不同的 Alamofire.xcodeproj 目录，每个目录都嵌套在 Products 目录中两个不同的 Alamofire.framework。

    您选择哪个 Products 目录无关紧要，但您选择的是顶部还是底部的 Alamofire.framework。

  • 对于 iOS 选择顶部的 Alamofire.framework，对于 macOS 选择底部的。

    您可以通过查看您项目的构建日志来验证您选择了哪个。Alamofire 的构建目标是列表中的 Alamofire iOS，Alamofire macOS，Alamofire tvOS 或 Alamofire watchOS。

  • 就是这样！

    Alamofire.framework会在编译阶段自动添加为目标依赖、链接库和嵌入库，这是在模拟器和设备上构建所必需的。

使用方法

发起请求

import Alamofire

Alamofire.request("https://httpbin.org/get")

响应处理

处理Alamofire发起的请求的响应，涉及到将响应处理程序链接到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)")
    }
}

在上面的示例中，当Request完成时，将responseJSON处理程序附加到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会话代理转发所有信息。它是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，并且值将是类型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，并将是类型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，并将是类型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 类型。

手动验证

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 - 将编码后的查询字符串结果设置为您请求的 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", parameters: parameters)
Alamofire.request("https://httpbin.org/post", parameters: parameters, encoding: URLEncoding.default)
Alamofire.request("https://httpbin.org/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方法会自动向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 接收到，凭证被添加，并由底层的 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.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。恢复数据可以通过下载响应访问，然后在尝试重新启动请求时重新使用。

重要：在最新发布的所有苹果平台（iOS 10、macOS 10.12、tvOS 10、watchOS 3）上，由于背景 URL 会话配置中的 resumeData 逻辑存在根本性问题，导致 resumeData 功能已损坏。在 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 在 Request 生命周期的各个阶段收集时间信息，并创建一个 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.default.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
        )
    }
}

总的来说，默认实现或覆盖闭包应提供所需的所有功能。应该只在最后一种情况下使用子类化。

需要注意的是，子代表除非在默认实现中初始化和销毁。当子类化时，请注意以避免引入内存泄漏。

请求

request、download、upload 或 stream 方法的结果是继承自 Request 的 DataRequest、DownloadRequest、UploadRequest 和 StreamRequest。所有 Request 实例都是由会话管理器创建的，永远不会直接初始化。

每个子类都有专门的方法，例如 authenticate、validate、responseJSON 和 uploadProgress，这些方法每个都返回调用实例，以便便于方法链式调用。

请求可以被暂停、恢复和取消

  • suspend()：暂停底层任务和调度队列。
  • resume()：恢复底层任务和调度队列。如果拥有者管理器将 startRequestsImmediately 设置为 true，则请求必须调用 resume() 才能启动。
  • cancel()：取消底层任务，生成一个传递给任何已注册响应处理器的错误。

请求路由

随着应用程序的增大，在构建出你的网络堆栈时采用常用模式非常重要。这个设计的一个重要部分就是如何路由你的请求。Alamofire 的 URLConvertible 和 URLRequestConvertible 协议以及 Router 设计模式都是为了解决这个问题而出现的。

URLConvertible

采用 URLConvertible 协议的类型可以用于构建 URL，这些 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。这通常涉及生成一个访问令牌，授权你的应用程序或用户调用各种支持的 Web 服务。当创建这些初始访问令牌可能很费力时，当访问令牌过期并需要获取新的令牌时，可能会更复杂。这里有很多需要考虑的线程安全问题。

RequestAdapter 和 RequestRetrier 协议被创建，以便更容易为特定一批 Web 服务创建线程安全的认证系统。

请求适配器

请求适配器（RequestAdapter）协议允许在创建前对在会话管理器（SessionManager）上发出的每一个请求进行检查和适配。使用适配器的一个非常具体的方式是在特定类型的认证之后，给请求追加一个 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）协议允许在执行过程中遇到错误的请求进行重试。当同时使用请求适配器（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)
}

一旦OAuth2处理程序（OAuth2Handler）被应用到会话管理器（SessionManager）的适配器和重试器，它将自动刷新访问令牌，并按相同的顺序重试所有失败请求，以处理无效访问令牌错误。

如果需要在创建时相同的顺序中执行它们，可以按任务标识符对它们进行排序。

上面的例子只检查了响应码为 401 的情况，这并远远不够强大，但它确实展示了如何检查无效访问令牌错误。在生产应用程序中，你希望检查 realm 以及很可能是 www-authenticate 报头，但这取决于OAuth2的具体实现。

另一个重要的注意事项是，这个认证系统可以由多个会话管理器共享。例如，你可能需要对一组Web服务使用 default 和 ephemeral 会话配置。上面的示例允许相同的 oauthHandler 实例在多个会话管理器之间共享，以管理单个刷新流程。

自定义响应序列化

处理错误

在实现自定义响应序列化程序或对象序列化方法之前，考虑如何处理可能发生的任何错误是很重要的。有两种基本选项：无修改地传递现有的错误，以便在响应时处理；或者，将所有错误封装在你应用程序特定的错误类型 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框架提供的Apple内置验证来评估由服务器提供的证书链。虽然这确保了证书链有效，但它不能防止中间人攻击（MITM）或其他潜在漏洞。为了减轻MITM攻击，处理敏感客户数据或财务信息的应用程序应使用由ServerTrustPolicy提供的证书或公钥固定。

服务器信任策略

ServerTrustPolicy枚举在通过安全的HTTPS连接连接到服务器时，评估一般由URLAuthenticationChallenge提供的服务器信任。

let serverTrustPolicy = ServerTrustPolicy.pinCertificates(
    certificates: ServerTrustPolicy.certificatesInBundle(),
    validateCertificateChain: true,
    validateHost: true
)

存在许多不同的服务器信任评估情况，让您完全控制验证过程。

  • performDefaultEvaluation：使用默认服务器信任评估，同时允许您控制是否验证由挑战提供的宿主机。
  • pinCertificates：使用固定证书来验证服务器信任。如果固定的证书之一与服务器证书之一匹配，则认为服务器信任是有效的。
  • pinPublicKeys：使用固定公钥来验证服务器信任。如果固定的公钥之一与服务器证书的公钥之一匹配，则认为服务器信任是有效的。
  • disableEvaluation：禁用所有评估，这反过来又会始终认为任何服务器信任都有效。
  • customEvaluation：使用关联的闭包来评估服务器信任的有效性，从而在验证过程中给您提供完全控制。请谨慎使用。

服务器信任策略管理器

ServerTrustPolicyManager负责将服务器信任策略的内部映射存储到特定的宿主机。这样可以允许Alamofire评估每个宿主机与不同的服务器信任策略。

let serverTrustPolicies: [String: ServerTrustPolicy] = [
    "test.example.com": .pinCertificates(
        certificates: ServerTrustPolicy.certificatesInBundle(),
        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) 错误，您可能遇到了这个问题。Apple 的 ATS 系统将覆盖整个挑战系统，除非您在应用程序的 plist 中配置 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 接收挑战回调，必须将 NSExceptionAllowsInsecureHTTPLoads 设置为 YES。一旦挑战回调被调用，ServerTrustPolicyManager 将接管服务器信任评估。如果您尝试连接仅支持 TLS 版本小于 1.2 的主机，您可能还需要指定 NSTemporaryExceptionMinimumTLSVersion。

在 production 环境中，建议始终使用有效的证书。

网络可达性

NetworkReachabilityManager 监听 WWAN 和 WiFi 网络接口的主机和地址的可达性变化。

let manager = NetworkReachabilityManager(host: "www.apple.com")

manager?.listener = { status in
    print("Network Status Changed: \(status)")
}

manager?.startListening()

请记住在上面的示例中保留 manager，否则不会报告任何状态变化。

在使用网络可达性来决定下一步行动时，有一些重要事项需要记住。

  • 不要 使用可达性来确定是否应该发送网络请求。
    • 您应该 始终 发送。
  • 在网络可达性恢复时，使用事件重试失败的网络请求。
    • 即使网络请求可能仍然会失败，这也是重试它们的好时机。
  • 网络可达性状态可以用于确定为什么一个网络请求可能失败。
    • 如果一个网络请求失败，告知用户网络请求失败是因为离线状态而不是更技术性的错误（如“请求超时”）会更有用。

建议查阅WWDC 2012 会话 706，“网络最佳实践”获取更多信息。

开放雷达

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

  • rdar://21349340 - 测试用例中的免费桥接问题导致编译器抛出警告
  • rdar://26761490 - Swift 字符串插值导致内存泄漏（常见使用情况）
  • rdar://26870455 - 背景URL会话配置在模拟器中不起作用
  • rdar://26849668 - 某些 URLProtocol API 未能正确处理 URLRequest

常见问题解答

Alamofire 命名的由来是什么？

Alamofire 的名字来源于阿拉莫火花，它是德克萨斯州州花蓝bonnet 的杂交变种。

路由器与请求适配器中应包含哪些逻辑？

简单、静态数据，如路径、参数和常见头部，应放在 Router 中。如根据身份验证系统值可能改变的 Authorization 头部这样的动态数据，应放在 RequestAdapter 中。

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

致谢

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

安全披露

如果您认为您发现了与 Alamofire 相关的安全漏洞，请您尽快通过电子邮件向 [email protected] 报告。请勿将其发布到公共问题跟踪器。

捐赠

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

  • 支付我们注册为联邦非营利组织的法律费用
  • 支付我们每年的法律费用以保持非营利组织的良好状态
  • 支付我们的邮件服务器费用，以帮助我们处理所有问题和安全问题
  • 可能为测试服务器提供资金，以使我们更容易测试边缘情况
  • 可能为开发者提供资金，使他们能够全职工作在我们的项目之一

Apache软件基金会（ASF）库在社区中的普及程度令人惊叹。我们对大家对项目的热情感到非常谦虚，并希望继续尽我们所能推进项目。在您的持续支持下，ASF能够提高其影响力，并为核心成员提供更好的法律保障。如果您在工作中使用了我们的任何库，请看看您的雇主是否有意愿进行捐赠。我们的初步目标是筹集1000美元，以便使我们的法律事务井井有条并启动这次活动。今天你所能捐出的任何金额都将是帮助我们实现目标的极大帮助。

Click here to lend your support to: Alamofire Software Foundation and make a donation at pledgie.com !

许可协议

Alamofire遵循MIT许可协议。详情请参阅LICENSE文件。