Unsplash-Swift 0.3.0

您需要将下面类似的代码 pod 'Unsplash-Swift', '~> 0.3' 添加到 Podfile 中

target 'MyApp' do
  pod 'Unsplash-Swift', '~> 0.3'
end

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

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

pod try Unsplash-Swift

Unsplash-Swift 0.3.0

由
muukii

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

特性

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

组件库

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

AlamofireImage - 一个图像库，包括图像响应序列化器、UIImage 和 UIImageView 扩展、自定义图像滤镜、自动清除内存缓存和基于优先级的图像下载系统。
AlamofireNetworkActivityIndicator - 使用 Alamofire 控制 iOS 上网络活动指示器的可见性。它包含可配置的延迟计时器，有助于减轻闪烁，并支持不由 Alamofire 管理的 NSURLSession 实例。

需求

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

迁移指南

沟通

如果您 需要帮助，请使用 Stack Overflow。 (标签 ‘alamofire’)
如果您想 询问一个问题，也请使用 Stack Overflow。
如果您 发现了错误，请开一个问题。
如果您 有任何功能请求，请开一个问题。
如果您 想作出贡献，请提交一个拉取请求。

安装

嵌入式框架要求最低部署目标为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：要设置为或附加到现有URL查询字符串的查询字符串，供GET、HEAD和DELETE请求使用，或设置为请求任何其他HTTP方法主体的内容。具有HTTP主体的编码请求的Content-Type HTTP标头字段设置为application/x-www-form-urlencoded。《_由于尚未发布有关如何编码集合类型的规范，Alamofire遵循在数组值键后追加[]的约定（例如foo[]=1&foo[]=2），以及为嵌套字典值追加键 surrounded by square brackets 的约定（例如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：使用关联的闭包值根据现有请求和参数构建新的请求。

自动编码NSURLRequest的参数

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 管理处理。

上传

支持的上传类型

文件
数据
流
multipartFormData

上传文件

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)
         }

上传 multipartFormData

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")
             }
         }

如果有可用的 resumeData，则自动将 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 Basic 认证

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)
             }
         }

时间线

Alamofire在Request的生命周期中收集时间，并创建一个以属性形式在Response上公开的Timeline对象。

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

上述报告以下Timeline信息

延迟：0.428秒
请求持续时间：0.428秒
序列化持续时间：0.001秒
总持续时间：0.429秒

可打印的

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)

鼓励与应用程序以显著方式交互的应用程序有自己的自定义类型遵守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)

鼓励与应用程序以显著方式交互的应用程序有自己的自定义类型遵守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

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

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 握手：
- 证书链必须是有效的。
- 证书链必须包含一个固定的证书。
- 挑战主机必须与证书链的叶证书中的主机匹配。
insecure.expired-apis.com 永远不会评估证书链，并且始终允许 TLS 握手成功。
其他所有主机将使用 Apple 提供的默认评估。

子类化服务器信任策略管理器

如果您发现自己需要更灵活的服务器信任策略匹配行为（例如通配符域），那么请子类化 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。

应用传输安全

自iOS 9引入应用传输安全（ATS）以来，如果你在应用程序中使用了自定义的ServerTrustPolicyManager和多个ServerTrustPolicy对象，可能没有任何效果。如果你经常看到CFNetwork SSLHandshake failed (-9806)错误，你很可能是遇到了这个问题。除非你在应用程序的plist中配置ATS设置以禁用部分功能，否则Apple的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将接管服务器信任评估。如果你尝试连接到仅支持小于1.2版本的TLS的主机，你可能还需要指定NSTemporaryExceptionMinimumTLSVersion。

在生产环境中，始终使用有效的证书是一个好习惯。

网络可到达性

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

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

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

manager?.startListening()

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

使用网络可到达性确定下一步操作时，有一些重要事项需要注意。

切勿使用可到达性决定是否发送网络请求。
- 你应该始终发送它。
当可到达性恢复正常时，使用事件重试失败的网络请求。
- 即使网络请求仍然可能失败，这也是重试它们的好时机。
网络可到达性状态可以用来确定为什么网络请求可能失败。
- 如果一个网络请求失败，最好是告知用户由于离线而导致的网络请求失败，而不是更技术性的错误，例如“请求超时”。

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

开放异常报告

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

rdar://21349340 - 测试案例中由于公废桥接问题引起编译器抛出警告

常见问题解答

Alamofire这个名称的由来是什么？

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

致谢

Alamofire由Alamofire软件基金会拥有并维护。你可以在Twitter上关注它们（@AlamofireSF），以获取项目更新和发布。

安全披露

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

许可证

Alamofire 使用 MIT 许可证发布。详细信息请参阅 LICENSE 文件。

Unsplash-Swift 0.3.0

Unsplash-Swift 0.3.0

Unsplash-Swift 0.3.0

特性

组件库

需求

迁移指南

沟通

安装

手动

嵌入式框架

用法

发送请求

响应处理

响应序列化

响应处理器

响应数据处理器

响应字符串处理器

响应JSON处理器

链式响应处理器

HTTP方法

参数

带URL编解码参数的GET请求

带URL编解码参数的POST请求

参数编码

自动编码NSURLRequest的参数

用JSON编码的参数的POST请求

HTTP标题

缓存

上传

上传文件

带有进度的上传

上传 multipartFormData

下载

下载文件

使用默认下载目的地

带有进度的文件下载

访问失败下载的恢复数据

身份验证

HTTP Basic 认证

使用 NSURLCredential 进行认证

验证

手动验证

自动验证

时间线

可打印的

调试打印

输出（cURL）

高级用法

管理器

使用默认配置创建管理器

使用后台配置创建管理器

使用短暂配置创建管理器

修改会话配置

请求

响应序列化

创建自定义响应序列化器

通用响应对象序列化

URLStringConvertible

类型安全的路由

URLRequestConvertible

API参数抽象

CRUD & 授权

安全

ServerTrustPolicy

服务器信任策略管理器

子类化服务器信任策略管理器

验证主机

验证证书链

应用传输安全

网络可到达性

开放异常报告

常见问题解答

Alamofire这个名称的由来是什么？

致谢

安全披露

许可证

使用 `NSURLCredential` 进行认证