# Alamofire 使用文档完整翻译

原文链接：github.com/Alamofire/A...‑alamofire说明：Alamofire 是 iOS/macOS 平台上非常流行的 Swift HTTP 网络库，下面完整翻译 Usage.md 使用指南，保留原有章节结构。

使用 Alamofire

导入 Alamofire 之后，就可以调用 AF 命名空间下的 API。

发起请求

swift

vbscript 复制代码

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

请求方法

HTTP 请求方法在 HTTPMethod 枚举中定义：

swift

ini 复制代码

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

在 AF.request(_:method:parameters:encoding:headers:interceptor:) 中可以指定请求方法：

swift

sql 复制代码

AF.request("https://httpbin.org/post", method: .post)
AF.request("https://httpbin.org/put", method: .put)
AF.request("https://httpbin.org/delete", method: .delete)

.get 是默认请求方法，method 参数可以省略。

请求参数与参数编码

Alamofire 支持通过 Parameters（[String: Any]字典）传入请求参数，并且支持多种编码方式。

URL 编码（URL‑encoded）

swift

less 复制代码

let parameters: [String: Any] = [    "foo": "bar",    "baz": ["a", 1],
    "qux": [        "x": 1    ]
]

AF.request("https://httpbin.org/get", parameters: parameters)
// 等价于：
AF.request("https://httpbin.org/get", parameters: parameters, encoding: .urlEncodedInURL)

GET、HEAD、DELETE 请求，默认使用 URLEncoding，参数拼接在 URL 查询字符串上。

JSON 编码

swift

less 复制代码

AF.request("https://httpbin.org/post", method: .post, parameters: parameters, encoding: .json)

请求体将编码为 JSON，设置请求头 Content‑Type: application/json。

表单编码

swift

less 复制代码

AF.request("https://httpbin.org/post", method: .post, parameters: parameters, encoding: .formUrlEncoded)

编码为 application/x‑www‑form‑urlencoded 表单格式，放在 http body。

⚠️ 注意：对于复杂嵌套的 Swift 集合类型，formUrlEncoded 编码行为可能不符合你的预期，尽量避免嵌套结构。

自定义编码

实现 ParameterEncoder 协议，就可以自定义参数编码逻辑。

请求头 Headers

设置请求头，传入 HTTPHeaders 对象：

swift

css 复制代码

let headers: HTTPHeaders = [
    .accept("application/json"),
    .authorization(username: "username", password: "password"),
    .userAgent("My‑App‑Name/v1.0.0 (com.example.MyApp; build:1)")
]

AF.request("https://httpbin.org/headers", headers: headers)

也可以手动构造：

swift

ini 复制代码

let headers: HTTPHeaders = [
    "Accept": "application/json",
    "Authorization": "Basic xxxxxxx"
]

请求拦截器 RequestInterceptor

RequestInterceptor 可以拦截、修改请求，也可以处理重试逻辑。

swift

scss 复制代码

let interceptor = MyCustomInterceptor()
AF.request("https://httpbin.org/get", interceptor: interceptor)

响应处理 Response Handling

处理数据响应

swift

vbscript 复制代码

AF.request("https://httpbin.org/get").responseData { response in
    debugPrint(response)
}

处理字符串响应

swift

vbscript 复制代码

AF.request("https://httpbin.org/get").responseString { response in
    print("响应字符串: (response.value ?? "")")
}

JSON 响应（旧版 API）

⚠️ 建议优先使用 responseDecodable，不推荐使用 responseJSON，该接口已逐渐废弃。

swift

vbscript 复制代码

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

Decodable 自动模型解析（推荐）

遵循 Decodable 的 Swift 结构体，可以直接把返回 JSON 转为模型对象：

swift

vbscript 复制代码

struct User: Decodable {
    let id: Int
    let name: String
}

AF.request("https://httpbin.org/get").responseDecodable(of: User.self) { response in
    switch response.result {
    case .success(let user):
        print("用户名称：(user.name)")
    case .failure(let error):
        print("解析失败：(error)")
    }
}

自定义解码器 JSONDecoder

swift

javascript 复制代码

let decoder = JSONDecoder()
decoder.dateDecodingStrategy = .iso8601

AF.request("https://httpbin.org/get")
    .responseDecodable(of: User.self, decoder: decoder) { response in
        // ...
    }

Response 结果枚举 Result

所有回调的 response.result 是 Result<Success, AFError> 类型：

swift

vbscript 复制代码

AF.request("https://httpbin.org/get").responseData { response in
    switch response.result {
    case .success(let data):
        print("收到字节：(data.count)")
    case .failure(let error):
        print("网络错误：(error.localizedDescription)")
    }
}

也可以读取 response.value / response.error 可选属性快速访问。

HTTP 状态码校验 Validation

默认 Alamofire不会校验 http 状态码，200‑299 以外的状态码默认视为成功。调用 .validate() 开启校验，非 2xx 状态码会返回失败：

swift

vbscript 复制代码

AF.request("https://httpbin.org/get")
    .validate()
    .responseData { response in
        // 4xx/5xx 会进入 failure
    }

自定义校验范围：

swift

vbscript 复制代码

AF.request("https://httpbin.org/get")
    .validate(statusCode: 200..<300)
    .responseData { _ in }

校验响应头：

swift

vbscript 复制代码

AF.request("https://httpbin.org/get")
    .validate(contentType: ["application/json"])
    .responseData { _ in }

文件上传 Upload

上传 Data

swift

kotlin 复制代码

let data = Data("hello world".utf8)
AF.upload(data, to: "https://httpbin.org/post")

上传本地文件

swift

less 复制代码

let fileUrl = URL(fileURLWithPath: "/path/to/file.txt")
AF.upload(fileUrl, to: "https://httpbin.org/post")

MultipartFormData 表单上传（多表单、文件）

swift

less 复制代码

AF.upload(multipartFormData: { multipart in
    multipart.append("foo".data(using: .utf8)!, withName: "key")
    multipart.append(fileUrl, withName: "file", fileName: "photo.jpg", mimeType: "image/jpeg")
}, to: "https://httpbin.org/post")
.responseData { response in
    // 上传完成回调
}

监听上传进度

swift

scss 复制代码

AF.upload(...)
    .uploadProgress { progress in
        print("上传进度：(progress.fractionCompleted)")
    }
    .responseData { _ in }

文件下载 Download

简单下载

swift

vbscript 复制代码

AF.download("https://httpbin.org/image/png")
    .responseURL { response in
        // response.value 是下载到本地的临时文件URL
    }

指定保存路径

swift

vbscript 复制代码

let destination: DownloadRequest.Destination = { _, response in
    let documentsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
    let fileURL = documentsURL.appendingPathComponent(response.suggestedFilename!)
    return (fileURL, [.removePreviousFile, .createIntermediateDirectories])
}

AF.download("https://httpbin.org/image/png", to: destination)
    .responseURL { response in
        // 文件已经保存到指定路径
    }

监听下载进度

swift

scss 复制代码

AF.download(...)
    .downloadProgress { progress in
        print("下载进度：(progress.fractionCompleted)")
    }
    .responseURL { _ in }

断点续传

Alamofire 支持使用 resumeData 恢复中断的下载任务。

URLSession 底层配置（Session）

AF 只是默认 Session 的简写，你可以创建自定义 Session，自定义 URLSession 配置：

swift

ini 复制代码

let configuration = URLSessionConfiguration.af.default
configuration.timeoutIntervalForRequest = 30

let session = Session(configuration: configuration)
session.request("https://httpbin.org/get")

关闭缓存

swift

ini 复制代码

let config = URLSessionConfiguration.af.default
config.requestCachePolicy = .reloadIgnoringLocalCacheData
let session = Session(configuration: config)

后台会话（后台下载）

⚠️ 后台会话有很多系统限制，需要实现系统的代理回调。

认证 Authentication

HTTP Basic 基础认证

swift

less 复制代码

AF.request("https://httpbin.org/basic-auth/user/pass")
    .authenticate(username: "user", password: "pass")
    .responseData { response in }

基于 URLCredential 凭证

swift

less 复制代码

let credential = URLCredential(user: "user", password: "pass", persistence: .forSession)
AF.request("https://httpbin.org/basic-auth/user/pass")
    .authenticate(with: credential)
    .responseData { _ in }

注意：服务端返回 401 挑战时认证才会生效；提前注入请求头 Authorization 可以直接带凭证。

链式请求与异步等待（Swift Concurrency / Async‑Await）

Alamofire 5.5+ 完整支持 Swift async/await

swift

rust 复制代码

// 直接 await 获取解码后的模型
let user = try await AF.request("https://httpbin.org/get").serializingDecodable(User.self).value

swift

swift 复制代码

// 捕获错误
do {
    let data = try await AF.request("https://httpbin.org/get").serializingData().value
} catch {
    print(error)
}

旧的回调闭包方式依然可用，推荐新项目使用 async‑await。

网络请求可打印输出 Debug

swift

scss 复制代码

AF.request("https://httpbin.org/get")
    .cURLDescription { curl in
        print(curl) // 打印等价 curl 命令，调试非常好用
    }
    .responseData { _ in }

可以打印完整 curl 命令，包含请求头、参数，方便复制到终端复现问题。

错误处理 AFError

Alamofire 的所有错误都封装为 AFError，包含以下场景：

URL 编码失败
网络系统错误（无网络、超时）
HTTP 状态码校验失败
数据解析失败（JSON/Decodable）
文件读写失败

swift

vbscript 复制代码

if case let AFError.responseValidationFailed(reason) = error {
    if case .unacceptableStatusCode(code: let code) = reason {
        print("错误状态码：(code)")
    }
}

常见问题小提示

ATS(App Transport Security) ：访问 http 链接，需要在 Info.plist 配置 NSAppTransportSecurity。
线程：回调默认在主队列 返回；你可以在 Session 初始化时修改 queue 参数切换回调队列。
取消请求 ：let req = AF.request(...); req.cancel()
重定向 ：默认遵循重定向，可以通过 RedirectHandler 自定义重定向行为。

# Alamofire 使用文档 完整翻译

使用 Alamofire

发起请求

请求方法

请求参数与参数编码

URL 编码（URL‑encoded）

JSON 编码

表单编码

自定义编码

请求头 Headers

请求拦截器 RequestInterceptor

响应处理 Response Handling

处理数据响应

处理字符串响应

JSON 响应（旧版 API）

Decodable 自动模型解析（推荐）

自定义解码器 JSONDecoder

Response 结果枚举 Result

HTTP 状态码校验 Validation

文件上传 Upload

上传 Data

上传本地文件

MultipartFormData 表单上传（多表单、文件）

监听上传进度

文件下载 Download

简单下载

指定保存路径

监听下载进度

断点续传

URLSession 底层配置（Session）

关闭缓存

后台会话（后台下载）

认证 Authentication

HTTP Basic 基础认证

基于 URLCredential 凭证

链式请求与异步等待（Swift Concurrency / Async‑Await）

网络请求可打印输出 Debug

错误处理 AFError

常见问题小提示

# Alamofire 使用文档完整翻译