HTZNetworkingManager 1.0

您希望向 Podfile 中添加类似以下内容：

target 'MyApp' do
  pod 'HTZNetworkingManager', '~> 1.0'
end

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

或者要对其进行测试运行，运行以下命令：

pod try HTZNetworkingManager

HTZNetworkingManager 1.0

由
Kemar White

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

特性

[x] 链式请求/响应方法
[x] URL/JSON/plist 参数编码
[x] 上传文件/数据/流/multipartFormData
[x] 请求或暂停数据下载
[x] 使用 NSURLCredential 进行身份验证
[x] HTTP 响应验证
[x] TLS 证书和公开密钥锁定
[x] 进度闭包 & NSProgress
[x] cURL 调试输出
[x] 完全面的单元测试覆盖率
[x] 完整的文档

要求

iOS 8.0+ / Mac OS X 10.9+ / tvOS 9.0+ / watchOS 2.0+
Xcode 7.2+

迁移指南

沟通

如果您需要帮助，使用 Stack Overflow。 (标记为 'alamofire' )
如果您想问一个一般问题，使用 Stack Overflow。
如果您发现了一个错误，请创建一个问题。
如果您有功能请求，请创建一个问题。
如果您想做出贡献，提交一个 pull request。

安装

内嵌框架需要的最小部署目标为 iOS 8 或 OS X Mavericks (10.9)。

由于缺乏对框架的支持，Alamofire 已不再支持 iOS 7。没有框架，针对 iOS 7 进行 Travis-CI 测试需要第二个重复的目标。单独的测试套件需要导入所有 Swift 文件，测试需要复制并重写。这种分裂将难以维护，以确保 Alamofire 生态系统的最高质量。

手动

如果您不想使用上述任一依赖管理器，您可以手动将 Alamofire 集成到您的项目中。

嵌入式框架

打开终端，在顶级项目目录下通过cd命令进入，如果你的项目还没有被初始化为git仓库，请运行以下命令

$ git init

通过运行以下命令将Alamofire添加为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，为OS X选择底部的。

你可以通过检查项目的构建日志来验证你选择了哪一个。Alamofire的构建目标将显示为Alamofire iOS或Alamofire OSX。
这就完成了！

Alamofire.framework自动添加为目标依赖项、链接框架和嵌入框架，在复制文件构建阶段，这些都是你用于在模拟器和设备上构建所需的一切。

使用方法

发送请求

import Alamofire

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

响应处理

Alamofire.request(.GET, "https://httpbin.org/get", parameters: ["foo": "bar"])
         .responseJSON { response in
             print(response.request)  // original URL request
             print(response.response) // URL response
             print(response.data)     // server data
             print(response.result)   // result of response serialization

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

在Alamofire中执行网络操作是异步的。对于不熟悉异步编程概念的开发者来说，异步编程可能是一个令人沮丧的来源，但这样做有很好的原因。

而不是阻塞执行以等待服务器的响应，指定一个回调以处理在收到响应后。请求的结果只在响应处理程序的范围内可用。任何依赖于响应或从服务器收到的数据的执行必须在处理程序中完成。

响应序列化

内置响应方法

response()
responseData()
responseString(encoding: NSStringEncoding)
responseJSON(options: NSJSONReadingOptions)
responsePropertyList(options: NSPropertyListReadOptions)

响应处理程序

Alamofire.request(.GET, "https://httpbin.org/get", parameters: ["foo": "bar"])
         .response { request, response, data, error in
             print(request)
             print(response)
             print(data)
             print(error)
          }

response序列化器不会评估响应数据中的任何内容。它只是在URL会话代理中直接转发所有信息。我们强烈建议您利用其他响应序列化器，充分利用Response和Result类型。

响应数据处理程序

Alamofire.request(.GET, "https://httpbin.org/get", parameters: ["foo": "bar"])
         .responseData { response in
             print(response.request)
             print(response.response)
             print(response.result)
          }

字符串处理响应

Alamofire.request(.GET, "https://httpbin.org/get")
         .responseString { response in
             print("Success: \(response.result.isSuccess)")
             print("Response String: \(response.result.value)")
         }

JSON处理响应

Alamofire.request(.GET, "https://httpbin.org/get")
         .responseJSON { response in
             debugPrint(response)
         }

链式响应处理器

响应处理器甚至可以被链式调用

Alamofire.request(.GET, "https://httpbin.org/get")
         .responseString { response in
             print("Response String: \(response.result.value)")
         }
         .responseJSON { response in
             print("Response JSON: \(response.result.value)")
         }

HTTP方法

Alamofire.Method 列出了在 RFC 7231 §4.3 中定义的 HTTP 方法

public enum Method: String {
    case OPTIONS, GET, HEAD, POST, PUT, PATCH, DELETE, TRACE, CONNECT
}

这些值可以作为 Alamofire.request 方法的第一个参数传递

Alamofire.request(.POST, "https://httpbin.org/post")

Alamofire.request(.PUT, "https://httpbin.org/put")

Alamofire.request(.DELETE, "https://httpbin.org/delete")

参数

带有URL编码参数的GET请求

Alamofire.request(.GET, "https://httpbin.org/get", parameters: ["foo": "bar"])
// https://httpbin.org/get?foo=bar

带有URL编码参数的POST请求

let parameters = [
    "foo": "bar",
    "baz": ["a", 1],
    "qux": [
        "x": 1,
        "y": 2,
        "z": 3
    ]
]

Alamofire.request(.POST, "https://httpbin.org/post", parameters: parameters)
// HTTP body: foo=bar&baz[]=a&baz[]=1&qux[x]=1&qux[y]=2&qux[z]=3

参数编码

参数也可以使用 ParameterEncoding 枚举进行 JSON、属性列表或其他自定义格式的编码

enum ParameterEncoding {
    case URL
    case URLEncodedInURL
    case JSON
    case PropertyList(format: NSPropertyListFormat, options: NSPropertyListWriteOptions)
    case Custom((URLRequestConvertible, [String: AnyObject]?) -> (NSMutableURLRequest, NSError?))

    func encode(request: NSURLRequest, parameters: [String: AnyObject]?) -> (NSURLRequest, NSError?)
    { ... }
}

URL：为 GET、HEAD 和 DELETE 请求设置或追加任何现有 URL 查询的查询字符串，或作为具有任何其他 HTTP 方法的请求的主体设置。使用 HTTP 身体编解码的编码请求的 Content-Type HTTP 头字段设置为 application/x-www-form-urlencoded。由于尚未发布有关如何编码集合类型的规范，Alamofire 遵循将方括号 [] 追加到键值 (foo[]=1&foo[]=2) 的约定，对于嵌套字典值，追加键周围的方括号 (foo[bar]=baz)。
URLEncodedInURL：创建要设置或追加到任何现有 URL 查询的查询字符串。使用与 .URL 相同的实现，但始终将编码结果应用于 URL。
JSON：使用 NSJSONSerialization 创建参数对象的 JSON 表示，并将其作为请求的主体设置。编码请求的 Content-Type HTTP 头字段设置为 application/json。
PropertyList：使用 NSPropertyListSerialization 根据关联的格式和写入选项值创建参数对象的 plist 表示，并将其作为请求的主体设置。编码请求的 Content-Type HTTP 头字段设置为 application/x-plist。
Custom：使用关联的闭包值构造一个新的请求，给定现有的请求和参数。

ModelState

let URL = NSURL(string: "https://httpbin.org/get")!
var request = NSMutableURLRequest(URL: URL)

let parameters = ["foo": "bar"]
let encoding = Alamofire.ParameterEncoding.URL
(request, _) = encoding.encode(request, parameters: parameters)

带有JSON编码参数的POST请求

let parameters = [
    "foo": [1,2,3],
    "bar": [
        "baz": "qux"
    ]
]

Alamofire.request(.POST, "https://httpbin.org/post", parameters: parameters, encoding: .JSON)
// HTTP body: {"foo": [1, 2, 3], "bar": {"baz": "qux"}}

HTTP头

在全局 request 方法中直接支持向 Request 添加自定义 HTTP 头。这使得将 HTTP 头附加到可以不断变化的 Request 变得很容易。

对于不经常改变的 HTTP 头，建议在 NSURLSessionConfiguration 上设置它们，以便它们自动应用于由底层的 NSURLSession 创建的任何 NSURLSessionTask。

let headers = [
    "Authorization": "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
    "Content-Type": "application/x-www-form-urlencoded"
]

Alamofire.request(.GET, "https://httpbin.org/get", headers: headers)
         .responseJSON { response in
             debugPrint(response)
         }

缓存

缓存在系统框架级别由NSURLCache处理。

上传

支持的上传类型

文件
数据
流
多部分表单数据

上传文件

let fileURL = NSBundle.mainBundle().URLForResource("Default", withExtension: "png")
Alamofire.upload(.POST, "https://httpbin.org/post", file: fileURL)

带有进度的上传

Alamofire.upload(.POST, "https://httpbin.org/post", file: fileURL)
         .progress { bytesWritten, totalBytesWritten, totalBytesExpectedToWrite in
             print(totalBytesWritten)

             // This closure is NOT called on the main queue for performance
             // reasons. To update your ui, dispatch to the main queue.
             dispatch_async(dispatch_get_main_queue()) {
                 print("Total bytes written on main queue: \(totalBytesWritten)")
             }
         }
         .responseJSON { response in
             debugPrint(response)
         }

上传多部分表单数据

Alamofire.upload(
    .POST,
    "https://httpbin.org/post",
    multipartFormData: { multipartFormData in
        multipartFormData.appendBodyPart(fileURL: unicornImageURL, name: "unicorn")
        multipartFormData.appendBodyPart(fileURL: rainbowImageURL, name: "rainbow")
    },
    encodingCompletion: { encodingResult in
        switch encodingResult {
        case .Success(let upload, _, _):
            upload.responseJSON { response in
                debugPrint(response)
            }
        case .Failure(let encodingError):
            print(encodingError)
        }
    }
)

下载

支持的下载类型

请求
继续数据

下载文件

Alamofire.download(.GET, "https://httpbin.org/stream/100") { temporaryURL, response in
    let fileManager = NSFileManager.defaultManager()
    let directoryURL = fileManager.URLsForDirectory(.DocumentDirectory, inDomains: .UserDomainMask)[0]
    let pathComponent = response.suggestedFilename

    return directoryURL.URLByAppendingPathComponent(pathComponent!)
}

使用默认下载目标

let destination = Alamofire.Request.suggestedDownloadDestination(directory: .DocumentDirectory, domain: .UserDomainMask)
Alamofire.download(.GET, "https://httpbin.org/stream/100", destination: destination)

带有进度的文件下载

Alamofire.download(.GET, "https://httpbin.org/stream/100", destination: destination)
         .progress { bytesRead, totalBytesRead, totalBytesExpectedToRead in
             print(totalBytesRead)

             // This closure is NOT called on the main queue for performance
             // reasons. To update your ui, dispatch to the main queue.
             dispatch_async(dispatch_get_main_queue()) {
                 print("Total bytes read on main queue: \(totalBytesRead)")
             }
         }
         .response { _, _, _, error in
             if let error = error {
                 print("Failed with error: \(error)")
             } else {
                 print("Downloaded file successfully")
             }
         }

访问失败的下载的继续数据

Alamofire.download(.GET, "https://httpbin.org/stream/100", destination: destination)
         .response { _, _, data, _ in
             if let
                 data = data,
                 resumeDataString = NSString(data: data, encoding: NSUTF8StringEncoding)
             {
                 print("Resume Data: \(resumeDataString)")
             } else {
                 print("Resume Data was empty")
             }
         }

如果可用，data参数将自动填充resumeData。

let download = Alamofire.download(.GET, "https://httpbin.org/stream/100", destination: destination)
download.response { _, _, _, _ in
    if let
        resumeData = download.resumeData,
        resumeDataString = NSString(data: resumeData, encoding: NSUTF8StringEncoding)
    {
        print("Resume Data: \(resumeDataString)")
    } else {
        print("Resume Data was empty")
    }
}

身份验证

身份验证在系统框架级别由NSURLCredential和NSURLAuthenticationChallenge处理。

支持的认证方案

HTTP基本认证

在适当的Request上的authenticate方法将自动向NSURLAuthenticationChallenge提供一个NSURLCredential

let user = "user"
let password = "password"

Alamofire.request(.GET, "https://httpbin.org/basic-auth/\(user)/\(password)")
         .authenticate(user: user, password: password)
         .responseJSON { response in
             debugPrint(response)
         }

根据服务器实现，可能也需要适当的Authorization头

let user = "user"
let password = "password"

let credentialData = "\(user):\(password)".dataUsingEncoding(NSUTF8StringEncoding)!
let base64Credentials = credentialData.base64EncodedStringWithOptions([])

let headers = ["Authorization": "Basic \(base64Credentials)"]

Alamofire.request(.GET, "https://httpbin.org/basic-auth/user/password", headers: headers)
         .responseJSON { response in
             debugPrint(response)
         }

使用NSURLCredential进行身份验证

let user = "user"
let password = "password"

let credential = NSURLCredential(user: user, password: password, persistence: .ForSession)

Alamofire.request(.GET, "https://httpbin.org/basic-auth/\(user)/\(password)")
         .authenticate(usingCredential: credential)
         .responseJSON { response in
             debugPrint(response)
         }

验证

默认情况下，Alamofire将完成的任何请求视为成功，无论响应内容如何。在响应处理程序之前调用validate将生成错误，如果响应有不可接受的状态码或MIME类型。

手动验证

Alamofire.request(.GET, "https://httpbin.org/get", parameters: ["foo": "bar"])
         .validate(statusCode: 200..<300)
         .validate(contentType: ["application/json"])
         .response { response in
             print(response)
         }

自动验证

自动验证状态码在200...299范围内，并且响应的Content-Type头与请求的Accept头匹配（如果提供的话）。

Alamofire.request(.GET, "https://httpbin.org/get", parameters: ["foo": "bar"])
         .validate()
         .responseJSON { response in
             switch response.result {
             case .Success:
                 print("Validation Successful")
             case .Failure(let error):
                 print(error)
             }
         }

可打印

let request = Alamofire.request(.GET, "https://httpbin.org/ip")

print(request)
// GET https://httpbin.org/ip (200)

调试可打印

let request = Alamofire.request(.GET, "https://httpbin.org/get", parameters: ["foo": "bar"])

debugPrint(request)

输出（cURL）

$ curl -i \
    -H "User-Agent: Alamofire" \
    -H "Accept-Encoding: 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基于NSURLSession和Foundation URL加载系统构建。为了充分利用此框架，建议您熟悉底层网络堆栈的概念和功能。

推荐阅读

管理器

顶级便利方法，如Alamofire.request，使用一个共享的Alamofire.Manager实例，该实例使用默认NSURLSessionConfiguration进行配置。

因此，以下两个语句是等效的

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

let manager = Alamofire.Manager.sharedInstance
manager.request(NSURLRequest(URL: NSURL(string: "https://httpbin.org/get")!))

应用程序可以为后台和短暂会话创建管理器，以及自定义默认会话配置的新管理器，例如设置默认头（HTTPAdditionalHeaders）或超时间隔（timeoutIntervalForRequest）。

使用默认配置创建管理器

let configuration = NSURLSessionConfiguration.defaultSessionConfiguration()
let manager = Alamofire.Manager(configuration: configuration)

使用后台配置创建管理器

let configuration = NSURLSessionConfiguration.backgroundSessionConfigurationWithIdentifier("com.example.app.background")
let manager = Alamofire.Manager(configuration: configuration)

使用短暂配置创建管理器

let configuration = NSURLSessionConfiguration.ephemeralSessionConfiguration()
let manager = Alamofire.Manager(configuration: configuration)

修改会话配置

var defaultHeaders = Alamofire.Manager.sharedInstance.session.configuration.HTTPAdditionalHeaders ?? [:]
defaultHeaders["DNT"] = "1 (Do Not Track Enabled)"

let configuration = NSURLSessionConfiguration.defaultSessionConfiguration()
configuration.HTTPAdditionalHeaders = defaultHeaders

let manager = Alamofire.Manager(configuration: configuration)

强烈不建议用于Authorization或Content-Type头。相反，分别使用URLRequestConvertible和ParameterEncoding。

请求

request，upload或download方法的结果是一个Alamofire.Request实例。请求总是使用拥有管理器的构造方法创建，而不会直接初始化。

如authenticate，validate和responseData之类的方法定回调用者，以便方便地进行链式调用。

请求可以被挂起、恢复和取消

suspend()：挂起底层任务和调度队列
resume()：恢复底层任务和调度队列。如果拥有管理器的startRequestsImmediately未设置为true，请求必须调用resume()才能启动。
cancel()：取消底层任务，产生错误，并将其传递给任何已注册的响应处理程序。

响应序列化

创建自定义响应序列化器

Alamofire为字符串、JSON和属性列表提供了内置的响应序列化，但可以在Alamofire.Request的扩展中添加其他序列化器。

例如，以下是如何实现使用Ono的响应处理器的示例

extension Request {
    public static func XMLResponseSerializer() -> ResponseSerializer<ONOXMLDocument, NSError> {
        return ResponseSerializer { request, response, data, error in
            guard error == nil else { return .Failure(error!) }

            guard let validData = data else {
                let failureReason = "Data could not be serialized. Input data was nil."
                let error = Error.errorWithCode(.DataSerializationFailed, failureReason: failureReason)
                return .Failure(error)
            }

            do {
                let XML = try ONOXMLDocument(data: validData)
                return .Success(XML)
            } catch {
                return .Failure(error as NSError)
            }
        }
    }

    public func responseXMLDocument(completionHandler: Response<ONOXMLDocument, NSError> -> Void) -> Self {
        return response(responseSerializer: Request.XMLResponseSerializer(), completionHandler: completionHandler)
    }
}

泛型响应对象序列化

可以使用泛型提供自动、安全的响应对象序列化。

public protocol ResponseObjectSerializable {
    init?(response: NSHTTPURLResponse, representation: AnyObject)
}

extension Request {
    public func responseObject<T: ResponseObjectSerializable>(completionHandler: Response<T, NSError> -> Void) -> Self {
        let responseSerializer = ResponseSerializer<T, NSError> { request, response, data, error in
            guard error == nil else { return .Failure(error!) }

            let JSONResponseSerializer = Request.JSONResponseSerializer(options: .AllowFragments)
            let result = JSONResponseSerializer.serializeResponse(request, response, data, error)

            switch result {
            case .Success(let value):
                if let
                    response = response,
                    responseObject = T(response: response, representation: value)
                {
                    return .Success(responseObject)
                } else {
                    let failureReason = "JSON could not be serialized into response object: \(value)"
                    let error = Error.errorWithCode(.JSONSerializationFailed, failureReason: failureReason)
                    return .Failure(error)
                }
            case .Failure(let error):
                return .Failure(error)
            }
        }

        return response(responseSerializer: responseSerializer, completionHandler: completionHandler)
    }
}

final class User: ResponseObjectSerializable {
    let username: String
    let name: String

    init?(response: NSHTTPURLResponse, representation: AnyObject) {
        self.username = response.URL!.lastPathComponent!
        self.name = representation.valueForKeyPath("name") as! String
    }
}

Alamofire.request(.GET, "https://example.com/users/mattt")
         .responseObject { (response: Response<User, NSError>) in
             debugPrint(response)
         }

相同的处理方法也可以用来处理返回多个对象表示形式的端点。

public protocol ResponseCollectionSerializable {
    static func collection(response response: NSHTTPURLResponse, representation: AnyObject) -> [Self]
}

extension Alamofire.Request {
    public func responseCollection<T: ResponseCollectionSerializable>(completionHandler: Response<[T], NSError> -> Void) -> Self {
        let responseSerializer = ResponseSerializer<[T], NSError> { request, response, data, error in
            guard error == nil else { return .Failure(error!) }

            let JSONSerializer = Request.JSONResponseSerializer(options: .AllowFragments)
            let result = JSONSerializer.serializeResponse(request, response, data, error)

            switch result {
            case .Success(let value):
                if let response = response {
                    return .Success(T.collection(response: response, representation: value))
                } else {
                    let failureReason = "Response collection could not be serialized due to nil response"
                    let error = Error.errorWithCode(.JSONSerializationFailed, failureReason: failureReason)
                    return .Failure(error)
                }
            case .Failure(let error):
                return .Failure(error)
            }
        }

        return response(responseSerializer: responseSerializer, completionHandler: completionHandler)
    }
}

final class User: ResponseObjectSerializable, ResponseCollectionSerializable {
    let username: String
    let name: String

    init?(response: NSHTTPURLResponse, representation: AnyObject) {
        self.username = response.URL!.lastPathComponent!
        self.name = representation.valueForKeyPath("name") as! String
    }

    static func collection(response response: NSHTTPURLResponse, representation: AnyObject) -> [User] {
        var users: [User] = []

        if let representation = representation as? [[String: AnyObject]] {
            for userRepresentation in representation {
                if let user = User(response: response, representation: userRepresentation) {
                    users.append(user)
                }
            }
        }

        return users
    }
}

Alamofire.request(.GET, "http://example.com/users")
         .responseCollection { (response: Response<[User], NSError>) in
             debugPrint(response)
         }

URLStringConvertible

采用URLStringConvertible协议的类型可以用来构建URL字符串，然后用来构建URL请求。NSString、NSURL、NSURLComponents和NSURLRequest默认遵循URLStringConvertible协议，允许将它们中的任何一个作为URLString参数传递给request、upload和download方法。

let string = NSString(string: "https://httpbin.org/post")
Alamofire.request(.POST, string)

let URL = NSURL(string: string)!
Alamofire.request(.POST, URL)

let URLRequest = NSURLRequest(URL: URL)
Alamofire.request(.POST, URLRequest) // overrides `HTTPMethod` of `URLRequest`

let URLComponents = NSURLComponents(URL: URL, resolvingAgainstBaseURL: true)
Alamofire.request(.POST, URLComponents)

与Web应用有重大交互的应用程序应鼓励自定义类型遵循URLStringConvertible，这是一种方便将特定领域模型映射到服务器资源的方式。

类型安全路由

extension User: URLStringConvertible {
    static let baseURLString = "http://example.com"

    var URLString: String {
        return User.baseURLString + "/users/\(username)/"
    }
}

let user = User(username: "mattt")
Alamofire.request(.GET, user) // http://example.com/users/mattt

URLRequestConvertible

采用URLRequestConvertible协议的类型可以用来构建URL请求。NSURLRequest默认遵循URLRequestConvertible协议，允许它直接传递给request、upload和download方法（这是指定单个请求的自定义HTTP主体的推荐方法）。

let URL = NSURL(string: "https://httpbin.org/post")!
let mutableURLRequest = NSMutableURLRequest(URL: URL)
mutableURLRequest.HTTPMethod = "POST"

let parameters = ["foo": "bar"]

do {
    mutableURLRequest.HTTPBody = try NSJSONSerialization.dataWithJSONObject(parameters, options: NSJSONWritingOptions())
} catch {
    // No-op
}

mutableURLRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")

Alamofire.request(mutableURLRequest)

与Web应用有重大交互的应用程序应鼓励自定义类型遵循URLRequestConvertible，以确保请求端点的持续性。这种方法可以用来抽象服务端的不一致性，提供类型安全的路由，并管理认证凭据和其他状态。

API参数抽象

enum Router: URLRequestConvertible {
    static let baseURLString = "http://example.com"
    static let perPage = 50

    case Search(query: String, page: Int)

    // MARK: URLRequestConvertible

    var URLRequest: NSMutableURLRequest {
        let result: (path: String, parameters: [String: AnyObject]) = {
            switch self {
            case .Search(let query, let page) where page > 1:
                return ("/search", ["q": query, "offset": Router.perPage * page])
            case .Search(let query, _):
                return ("/search", ["q": query])
            }
        }()

        let URL = NSURL(string: Router.baseURLString)!
        let URLRequest = NSURLRequest(URL: URL.URLByAppendingPathComponent(result.path))
        let encoding = Alamofire.ParameterEncoding.URL

        return encoding.encode(URLRequest, parameters: result.parameters).0
    }
}

Alamofire.request(Router.Search(query: "foo bar", page: 1)) // ?q=foo%20bar&offset=50

CRUD & 授权

enum Router: URLRequestConvertible {
    static let baseURLString = "http://example.com"
    static var OAuthToken: String?

    case CreateUser([String: AnyObject])
    case ReadUser(String)
    case UpdateUser(String, [String: AnyObject])
    case DestroyUser(String)

    var method: Alamofire.Method {
        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

    var URLRequest: NSMutableURLRequest {
        let URL = NSURL(string: Router.baseURLString)!
        let mutableURLRequest = NSMutableURLRequest(URL: URL.URLByAppendingPathComponent(path))
        mutableURLRequest.HTTPMethod = method.rawValue

        if let token = Router.OAuthToken {
            mutableURLRequest.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
        }

        switch self {
        case .CreateUser(let parameters):
            return Alamofire.ParameterEncoding.JSON.encode(mutableURLRequest, parameters: parameters).0
        case .UpdateUser(_, let parameters):
            return Alamofire.ParameterEncoding.URL.encode(mutableURLRequest, parameters: parameters).0
        default:
            return mutableURLRequest
        }
    }
}

Alamofire.request(Router.ReadUser("mattt")) // GET /users/mattt

安全

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

服务器信任策略

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

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 manager = Manager(
    serverTrustPolicyManager: ServerTrustPolicyManager(policies: serverTrustPolicies)
)

请确保保留对新的 Manager 实例的引用，否则当你的 manager 被释放时，所有请求都将被取消。

这些服务器信任策略将导致以下行为

test.example.com 总是使用证书固定，证书链和主机验证已启用，因此需要满足以下条件才能允许 TLS 握手成功
- 证书链必须是有效的。
- 证书链必须包含一个已固定的证书。
- challenge 主机必须与证书链中叶证书中的主机匹配。
insecure.expired-apis.com 将永远不会评估证书链，并始终允许 TLS 握手成功。
所有其他主机将使用 Apple 提供的默认评估。

子类化 Server Trust Policy Manager

如果你发现自己需要更灵活的服务器信任策略匹配行为（例如通配符域名），那么就子类化 ServerTrustPolicyManager 并用你自己的自定义实现覆盖 serverTrustPolicyForHost 方法。

class CustomServerTrustPolicyManager: ServerTrustPolicyManager {
    override func serverTrustPolicyForHost(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。

App Transport Security

随着 iOS 9 中 App Transport Security (ATS) 的引入，使用具有多个 ServerTrustPolicy 对象的自定义 ServerTrustPolicyManager 可能没有任何效果。如果你持续看到 CFNetwork SSLHandshake failed (-9806) 错误，你可能遇到了这个问题。Apple 的 ATS 系统除非你在应用程序的 Info.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。

建议在生产环境中始终使用有效证书。

组件库

为了使 Alamofire 专注于核心网络实现，Alamofire 软件基金会创建了额外的组件库，以向 Alamofire 生态系统添加更多功能。

AlamofireImage - 一个图像库，包括图像响应序列化器、UIImage 和 UIImageView 扩展、自定义图像过滤、内存缓存自动清理以及基于优先级的图像下载系统。

开放的 rdars

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

rdar://21349340 - 由于测试案例中的免费用桥接问题导致的编译器抛出警告

常见问题解答

Alamofire 命名的由来是什么？

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

致谢

Alamofire 由 Alamofire 软件基金会拥有和维护。您可以在 Twitter 上关注他们的动态，了解项目更新和发布信息：@AlamofireSF。

安全披露

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

许可

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