Alamofire 2.0 迁移指南：Result 驱动响应序列化与 Swift 2.0 时代的大版本重构

Alamofire 2.0 是 Alamofire 历史上一次以 Swift 2.0 为基线的重大版本跃迁，它用 Result 类型彻底重塑了响应序列化体系、重写了 URLRequestConvertible 与 MultipartFormData 的错误处理，并开放了参数编码、服务器信任策略等底层 ACL。本文基于仓库中的 Alamofire 2.0 Migration Guide 完整梳理这些破坏性变更与新增能力，并结合当前仓库源码，说明这些设计在后续版本中如何演进，帮助熟悉 Alamofire 1.x 的开发者理解迁移背后的工程动机。

一、新版本支持矩阵

迁移指南首先明确了 Alamofire 2.0 的运行环境要求，这是所有迁移工作的前提：

• 正式支持 iOS 8+、Mac OS X 10.9+、watchOS，构建工具要求 Xcode 7，语言版本要求 Swift 2.0；
• 如果项目仍需要面向 iOS 7 与 Swift 1.x，官方指引是使用最新的 1.x 标签版本，二者不可混用。

这一约束在指南中被特别强调：“It is not possible to use Alamofire 2.0 without Swift 2.0”——Swift 2.0 不是可选依赖，而是 2.0 的硬性编译前提。当前仓库中 Package.swift 与 [e-mail] 等多份清单文件则展示了这一约束在后续版本中逐步抬升的轨迹：Swift 版本下限早已从 2.0 提升到 5/6 系列，读者在对照迁移文档时应注意其适用前提是该文档所对应的历史版本阶段。

二、Swift 2.0：贯穿所有模块的基座变更

指南将 Swift 2.0 列为 1.x 到 2.0 之间“最大的变化”。Swift 2 带来了三组直接改变库设计的能力：

1. 错误处理（do/catch、ErrorType）：替换了原先遍布各处的 NSError? 回调参数；
2. 协议扩展（protocol extensions）：让 URLRequestConvertible 等协议能提供默认实现；
3. 可用性检查（availability checking）：为后文 iOS 9 / OS X 10.11 的 StreamTask 支持提供了条件编译能力。

此外，guard 与 defer 这类新语法虽然不影响公共 API，但让实现代码更简洁——指南明确指出“所有源文件、测试逻辑与示例代码都已更新为 Swift 2.0 范式”。从源码结构看，当前仓库的 Source/ 目录（Core、Features、Extensions 三层）仍是当时重组后的延续，guard let parameters else 这类写法可以直接在 ParameterEncoding.swift 中见到。

三、响应序列化系统的重构（核心变更）

这是 2.0 中最显著的逻辑变更。1.x 中所有响应序列化器共用同一个完成回调签名：

public func response(completionHandler: (NSURLRequest, NSHTTPURLResponse?, AnyObject?, NSError?) -> Void) -> Self {
    return response(serializer: Request.responseDataSerializer(), completionHandler: completionHandler)
}

这种“双可选”设计（AnyObject? + NSError?）存在根本缺陷：检查其中一个为 nil 并不能保证另一个也不为 nil，调用方必须同时处理多种模糊状态。2.0 重设计了整个序列化流程，目标是既方便地访问未序列化的原始服务器数据，又能把响应序列化为非可选的 Result 类型。

3.1 不做序列化的 response

第一个 response 重载是非泛型的，不对服务器数据做任何处理，只是把 NSURLSessionDelegate 回调中累积的信息原样转发出来：

public func response(
	queue queue: dispatch_queue_t? = nil,
	completionHandler: (NSURLRequest?, NSHTTPURLResponse?, NSData?, ErrorType?) -> Void)
	-> Self
{
	delegate.queue.addOperationWithBlock {
		dispatch_async(queue ?? dispatch_get_main_queue()) {
			completionHandler(self.request, self.response, self.delegate.data, self.delegate.error)
		}
	}

	return self
}

两个迁移要点值得注意：

• data 的返回类型从 AnyObject? 变为 NSData?：不再需要手动把 AnyObject? 强转为 NSData?，类型安全直接由签名保证；
• 回调默认在 delegate.queue 上完成组装后，再派发到 queue ?? dispatch_get_main_queue()，即默认回到主队列，与 1.x 的行为保持一致。

3.2 泛型响应序列化器与 Result

第二个重载是真正强大的入口——利用泛型 + Result 消除“双可选”：

public func response<T: ResponseSerializer, V where T.SerializedObject == V>(
    queue queue: dispatch_queue_t? = nil,
    responseSerializer: T,
    completionHandler: (NSURLRequest?, NSHTTPURLResponse?, Result<V>) -> Void)
    -> Self
{
    delegate.queue.addOperationWithBlock {
        let result: Result<T.SerializedObject> = {
            if let error = self.delegate.error {
                return .Failure(self.delegate.data, error)
            } else {
                return responseSerializer.serializeResponse(self.request, self.response, self.delegate.data)
            }
        }()

        dispatch_async(queue ?? dispatch_get_main_queue()) {
            completionHandler(self.request, self.response, result)
        }
    }

    return self
}

实现逻辑分两支：底层 URLSession 报错时，直接构造携带原始数据的 .Failure（NSData? 被保留在失败分支里，便于调试）；无错时调用序列化器并得到 .Success 值。Result 本身的定义为：

public enum Result<Value> {
    case Success(Value)
    case Failure(NSData?, ErrorType)
}

指南还提到 Result 附带了大量便捷计算属性（如 isSuccess、value），并遵循 CustomStringConvertible 与 CustomDebugStringConvertible 以简化调试输出——所以示例代码里可以直接 print(result) 得到可读摘要。

对应到使用侧，2.0 提供了三个最常用的便捷序列化入口：

// Response Data
Alamofire.request(.GET, "http://httpbin.org/get")
         .responseData { _, _, result in
             print("Success: \(result.isSuccess)")
             print("Response: \(result)")
         }

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

// Response JSON
Alamofire.request(.GET, "http://httpbin.org/get")
         .responseJSON { _, _, result in
             print(result)
             debugPrint(result)
         }

迁移时只需把 1.x 的“分别判空”逻辑改写为对 Result 的 switch/guard case 解包，双可选分支问题即告消除。

3.3 错误类型：从 NSError 到 ErrorType

指南说明：Alamofire 运行时仍然只产生 NSError 对象，但所有 Result 类型改为存储 ErrorType，以便自定义序列化器可以使用任意 ErrorType。ValidationResult 与 MultipartFormDataEncodingResult 也做了同样的类型替换。这一决策的长期影响可以对照当前源码验证：ResponseSerialization.swift 中的 DataResponseSerializerProtocol 现在以 throws -> SerializedObject 表达序列化失败，协议参数中 error: (any Error)? 取代了当年的 ErrorType，正是 2.0 这一路线的直接延续。

四、URLRequestConvertible 返回可变请求对象

为了让非典型场景更容易定制，URLRequestConvertible 协议在 2.0 中被改为返回 NSMutableURLRequest：

public protocol URLRequestConvertible {
    var URLRequest: NSMutableURLRequest { get }
}

动机很直接：1.x 返回不可变对象时，编码后的请求体（例如需要追加 header、覆盖超时时间的第三方服务请求）无法再修改；改成 NSMutableURLRequest 后，可以在请求被 Session 发送前自由定制。指南指出该变更只影响少数用户。当前仓库中该协议已演进为 var urlRequest: URLRequest 的现代形式，协议本体与默认实现见 URLConvertible+URLRequestConvertible.swift。

五、Multipart FormData 改用 Swift 错误处理

1.x 中编码 MultipartFormData 会返回一个封装可能的编码错误 EncodingResult 枚举；2.0 直接改用 Swift 2.0 的 do/catch 错误处理，使用方式更自然：

let upload = Alamofire.upload(.POST, "http://httpbin.org/post") { multipartFormData in
    multipartFormData.append(data, withName: "file")
}
// 失败通过 .responseData / 错误回调抛出

指南强调该变更“大部分封装在内部，只影响极少数用户”。当前实现中，多部件上传的编码错误统一归入 AFError 的 multipartEncodingFailed 分支，测试覆盖位于 MultipartFormDataTests.swift。

六、ACL 更新与新特性

6.1 参数编码：开放内部实现与 .URLEncodedInURL

两个变化构成 2.0 参数编码的重构主线：

ACL 开放：ParameterEncoding 枚举此前藏在 internal / private ACL 之后，2.0 把 queryComponents 与 escape 方法开放出来，使自定义 .Custom 编码的实现成本大幅下降。

.URLEncodedInURL 新编码方式：旧版本中 .URL 编码会根据 HTTP 方法决定把查询串追加到 URL 还是 HTTP body——这对 GET 等场景成立，但让 PUT、POST 向 URL 追加查询参数变得很难。2.0 新增第二种 URL 编码 case .URLEncodedInURL，无论 HTTP 方法是什么，始终把查询串追加到 URL 上。

对照当前源码，这一设计最终沉淀为 URLEncoding.Destination 三值枚举（见 ParameterEncoding.swift）：

2.0 的 case	现代 Destination	行为
.URL	.methodDependent	GET/HEAD/DELETE 编码进 URL，其余方法编码进 body（默认）
.URLEncodedInURL	.queryString	始终编码进 URL 查询串
.URLForm	.httpBody	始终编码进 HTTP body

encodesParametersInURL(for:) 的分支逻辑与文档描述一一对应，测试位于 ParameterEncodingTests.swift。

6.2 服务器信任策略：可子类化的 ServerTrustPolicyManager

1.x 中 ServerTrustPolicyManager 的方法是 internal 的，无法实现自定义域名匹配。2.0 把内部实现提升为 public ACL，使通过子类化实现通配符域名（wildcarded domains）等灵活匹配成为可能：

class CustomServerTrustPolicyManager: ServerTrustPolicyManager {
    override func serverTrustPolicyForHost(host: String) -> ServerTrustPolicy? {
        var policy: ServerTrustPolicy?

        // Implement your custom domain matching behavior...

        return policy
    }
}

这一开放点对应后续版本中 ServerTrustEvaluation.swift 的 ServerTrustEvaluating 协议化体系——2.0 通过子类化扩展匹配行为，5.0 之后则通过组合 CompositeTrustEvaluator 等实现同等灵活性。

6.3 Download 请求对齐 Data 请求的构造方式

全局与 Manager 的 download API 在 2.0 中新增了 parameters 与 encoding 参数，以更好支持后台会话中的动态 payload。构造 download 请求从此与构造 data 请求完全同构，只是多一个 destination 参数：

public func download(
    method: Method,
    _ URLString: URLStringConvertible,
    parameters: [String: AnyObject]? = nil,
    encoding: ParameterEncoding = .URL,
    headers: [String: String]? = nil,
    destination: Request.DownloadFileDestination)
    -> Request
{
    return Manager.sharedInstance.download(
        method,
        URLString,
        parameters: parameters,
        encoding: encoding,
        headers: headers,
        destination: destination
    )
}

迁移要点：download 请求现在同样享受 ParameterEncoding 全家桶（含上文 2.0 新增的 .URLEncodedInURL），默认编码仍是 .URL。

6.4 Stream Tasks：NSURLSessionStreamTask 支持

2.0 为 iOS 9 与 OS X 10.11 增加了对 NSURLSessionStreamTask 的支持，同时扩展了 SessionDelegate 以覆盖全部新的 NSURLSessionStreamDelegate API。这一能力正是依赖前文提到的 Swift 2.0 可用性检查来按平台条件编译的——它也是 2.0 相比 1.x 唯一的“纯新增请求类型”，后续版本中流式处理的演进方向则体现在当前仓库的 DataStreamRequest.swift 中。

七、从 2.0 到当前仓库：设计遗产一览

把迁移指南中的每个 2.0 决策与当前源码对照，可以确认这些设计并非过渡方案，而是 Alamofire 至今的骨架：

• Result 语义：当年自定义的 Result<Success/Failure> 枚举，如今由标准库 Result 接管，Alamofire 仅保留类型别名与内部辅助扩展，见 Result+Alamofire.swift（AFResult<Success> = Result<Success, AFError>）；isSuccess / value / failure 等便捷访问正是指南预告的那批“convenience computed properties”的延续；
• 序列化器协议：ResponseSerializer 协议（T: ResponseSerializer, T.SerializedObject == V）的形态保留到了 ResponseSerialization.swift，并叠加了 DataPreprocessor（如 GoogleXSSIPreprocessor 处理 )]}',\n 前缀）与 emptyResponseCodes 等空体判定机制；
• 错误模型：2.0 引入的 ErrorType 化路径，最终收敛为统一枚举 AFError，其失败原因分支（parameterEncodingFailed、multipartEncodingFailed、responseSerializationFailed）与迁移文档中提到的各 *Result 类型一一对应；
• 迁移文档族：本指南与仓库中的 3.0 迁移指南、4.0 迁移指南、5.0 迁移指南 构成完整的版本演进脉络，日常用法则见 Usage.md。

八、迁移检查清单

基于文档内容，1.x 项目升级到 2.0 的最小动作可以归纳为：

1. 工具链切到 Xcode 7 + Swift 2.0，构建目标 iOS 8+ / OS X 10.9+；
2. 所有 response 回调从 (request, response, data, error) 四参数签名改为处理 Result<V> 的三参数签名，删除手动判空与 AnyObject 强转；
3. 依赖 data as? AnyObject 的地方直接使用强类型 NSData?；
4. 自定义序列化器把错误表示从 NSError? 换成 ErrorType，ValidationResult、MultipartFormDataEncodingResult 同步替换；
5. URLRequestConvertible 实现者返回 NSMutableURLRequest；
6. PUT/POST 需要查询串进 URL 的场景改用 .URLEncodedInURL；
7. 有通配域名匹配需求的 TLS 配置，通过子类化 ServerTrustPolicyManager 重写 serverTrustPolicyForHost(_:)。

Alamofire 2.0 的迁移表面是一次 API 改名潮，实质是把“成功与失败必须互斥”这一基本不变量写进了类型系统（Result），并把错误处理统一交给 Swift 语言机制。理解了这份文档中每一处变更的动机，再对照当前仓库的源码结构，就能完整把握 Alamofire 从 2.0 至今的架构主线。