Alamofire — 这是什么，基于 Swift 的 HTTP 客户端及其工作原理

什么是 Alamofire？

Alamofire 是一个用于 Swift 的 HTTP 客户端，由 Alamofire Software Foundation 创建（最初由 Mattt Thompson 于 2014 年创建）。该库抽象了 URLSession 的低级细节，为网络通信提供了简洁且富有表现力的 API。

Alamofire 的基本理念是链式语法，请求参数（URL、方法、标头、参数、编码器）通过连续调用传递。这使得代码更易读，并减少了与 URLRequest 配置错误相关的可能性。声明式方法 允许专注于需要做什么，而不是如何建立连接的细节。开发者描述期望的结果，而库负责低级的网络工作。

该库自 2014 年以来一直得到积极维护，并经历了七个主要版本。Alamofire 5 是 2025–2026 年的当前版本，支持 Combine、async/await、响应转换器、用于调试的 EventMonitor 以及用于请求拦截的 RequestInterceptor。每个主要版本都带来了重大改进：Alamofire 4 增加了 Codable 支持，Alamofire 5 增加了 Combine Publishers 和改进的请求拦截系统。

Alamofire 生态系统包括额外的库：AlamofireImage 用于加载和缓存图像，AlamofireNetworkActivityIndicator 用于 iOS 状态栏中的网络指示器，以及 AlamofireObjectMapper 用于与 ObjectMapper 集成。这些组件使 Alamofire 成为一个完整的网络栈，而不仅仅是 HTTP 客户端。

安装与配置

Alamofire 通过 Swift Package Manager（推荐）、CocoaPods 或 Carthage 安装。在 Xcode 中，只需打开 File → Add Packages 菜单，粘贴仓库 URL 并指定版本即可。

// Swift Package Manager — 添加到 Package.swift
dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git",
             from: "5.9.0")
]

// 在文件中导入
import Alamofire

安装后，Alamofire 通过命名空间 AF（Alamofire 的缩写）全局可用，无需额外配置。大多数项目从设置带有自己配置的 Session 开始——这允许设置基本 URL、标准标头、超时时间和 TLS 证书处理程序。

let configuration = URLSessionConfiguration.default
configuration.timeoutIntervalForRequest = 30
let session = Session(configuration: configuration)

通过 Session(configuration:) 创建自己的会话在需要为应用程序的不同部分设置独特配置时是必要的——例如，为具有激进缓存的图像加载设置单独的会话，以及为具有身份验证的 API 请求设置单独的会话。Alamofire 会话不仅接受配置，还接受 interceptor、serverTrustManager、cachedResponseHandler 和 redirectHandler，从而允许在请求的所有阶段完全控制网络行为。

主要功能

Alamofire 提供了广泛的功能，覆盖了 iOS 应用程序中的大多数网络通信场景。让我们看看其中的关键功能。

HTTP 请求

请求的基本语法包括方法、URL、参数和编码。所有标准 HTTP 方法都通过 HTTPMethod 枚举支持：get、post、put、patch、delete。参数可以编码为 URL 参数（URLEncoding）、JSON 主体（JSONEncoding）或 multipart 格式（MultipartFormData）。

AF.request("https://api.example.com/users", method: .post,
           parameters: ["name": "Alex", "role": "developer"])
    .validate()
    .responseDecodable(of: User.self) { response in
        switch response.result {
        case .success(let user):
            print("用户已创建: \(user)")
        case .failure(let error):
            print("错误: \(error)")
        }
    }

validate() 方法自动检查状态码（200–299）和内容类型，在非标准响应时返回错误，从而消除了手动检查 statusCode。responseDecodable 使用 Decodable 协议自动将 JSON 反序列化为 Swift 结构——这消除了手动 JSONSerialization，并减少了使用 REST API 时的样板代码量。

响应处理

Alamofire 支持多种响应处理程序类型：response（原始数据）、responseJSON（字典/数组）、responseString（文本）、responseData（Data）和 responseDecodable（Decodable 模型）。响应转换器 可以自定义创建——用于 protobuf、图形格式或自定义协议。

文件上传与下载

使用 upload 将数据上传到服务器，支持 Data、File 和 MultipartFormData。大文件的下载通过 download 进行，在连接中断或断开后可以通过 resumeData 恢复。两种操作都支持通过 uploadProgress 和 downloadProgress 跟踪进度，进度值为 0 到 1 之间的小数，用于在用户界面中显示。

使用 Alamofire 进行 Multipart 上传特别方便：upload(multipartFormData:) 方法接受一个闭包，在其中通过 append 添加表单部分。每个部分可以包含数据、文件或流，以及自己的名称和 mime 类型。Alamofire 自动计算 multipart 边界并设置正确的 Content-Type 标头，使开发者不必手动构建请求体。对于大文件，建议使用流传输（stream provider）而不是将整个文件加载到内存中——这可以防止在资源有限的移动设备上超出内存限制。一个典型场景——将用户头像与个人资料数据一起在一个 multipart 请求中发送，这减少了 HTTP 调用次数并简化了服务器端处理。

Alamofire 与 URLSession 比较

比较 Alamofire 和原生 URLSession 有助于做出架构决策。Alamofire 不会取代 URLSession——它构建在 URLSession 之上，并使用相同的配置、缓存和后台任务机制。URLSession 的所有功能都可以通过 Alamofire 使用，但具有更便捷的声明式语法。

在大型项目中，Alamofire 将网络请求代码量减少 30–50% 并简化错误处理。在小型项目或对二进制大小有严格要求的项目中，由于没有外部依赖，原生 URLSession 更受青睐。

现代 Alamofire 5 通过 publishDecodable 属性与 Combine 集成，该属性返回一个 Publisher，允许构建具有错误处理和数据转换的响应式请求链。对于 async/await，可以使用带有 value 后缀的方法——例如 AF.request(url).serializingDecodable(User.self).value，这使得语法极为简洁，并让人联想到使用原生 URLSession 的工作方式。使用 async/await 时，不再需要闭包，错误处理通过 Swift 的标准 do-catch 块执行，从而简化了代码的维护和长期可读性。

代码示例

让我们看一个更复杂的示例——一个带有拦截器的请求，该拦截器自动添加授权令牌并在 401 错误时重试。这是使用 JWT 身份验证的应用程序的典型场景。

class AuthInterceptor: RequestInterceptor {
    func adapt(_ urlRequest: URLRequest,
               for session: Session,
               completion: @escaping (Result<URLRequest, Error>) -> Void) {
        var request = urlRequest
        request.setValue("Bearer \(TokenManager.shared.token)",
                         forHTTPHeaderField: "Authorization")
        completion(.success(request))
    }

    func retry(_ request: Request,
              for session: Session,
              dueTo error: Error,
              completion: @escaping (RetryResult) -> Void) {
        guard let response = request.response,
              response.statusCode == 401
        else { return completion(.doNotRetry) }
        TokenManager.shared.refreshToken { success in
            completion(success ? .retry : .doNotRetry)
        }
    }
}

拦截器 AuthInterceptor 实现了两个协议：adapt（向每个请求添加令牌）和 retry（在 401 错误时尝试刷新令牌）。retry 方法检查响应的状态码，如果收到 401，则通过 TokenManager 请求新令牌。成功刷新后，请求自动重复。

在会话中使用拦截器：

let session = Session(interceptor: AuthInterceptor())
session.request("https://api.example.com/profile")
    .responseDecodable(of: Profile.self) { response in
        print(response.result)
    }

通过此会话的所有请求自动经过 AuthInterceptor——令牌被添加到标头，在 401 时执行刷新和重复。这消除了每个请求中身份验证代码的重复，并集中了令牌管理逻辑。