Alamofire 是 Swift 生態最知名的網路庫。它的公開介面乾淨到三行就能發一個請求,但底下其實是一層又一層的包裝。本文順著呼叫鏈往下挖,看看每個環節到底做了什麼。
Alamofire.request(.GET, "https://httpbin.org/get")
這行呼叫進到 Alamofire.swift 的全域函式:
public func request(method: Method,
URLString: URLStringConvertible,
parameters: [String: AnyObject]? = nil,
encoding: ParameterEncoding = .URL,
headers: [String: String]? = nil) -> Request {
return Manager.sharedInstance.request(method, URLString,
parameters: parameters,
encoding: encoding,
headers: headers)
}
五個參數各有分工:請求方法、網域、查詢參數、參數編碼方式、請求標頭。若 encoding 維持預設的 .URL,傳入的參數會被拼成 ?key=value&key2=value2 接在網址後面。
返回值型別是 Manager,那是對 NSURLSession 的一層封裝。sharedInstance 會用 NSURLSessionConfiguration.defaultSessionConfiguration() 建立 session,並塞入一組預設的 HTTP 標頭。
public func request(
method: Method,
_ URLString: URLStringConvertible,
parameters: [String: AnyObject]? = nil,
encoding: ParameterEncoding = .URL,
headers: [String: String]? = nil) -> Request {
let mutableURLRequest = URLRequest(method, URLString: URLString, headers: headers)
let encodedURLRequest = encoding.encode(mutableURLRequest, parameters: parameters).0
return request(encodedURLRequest)
}
這一層的職責很單純:先把 URL 與標頭組裝成 NSURLRequest,依編碼方式處理參數,最後把結果丟給 Request 的建構子。
以 .URL 編碼為例,實際拼字串的邏輯長這樣:
case .URL:
func query(parameters: [String: AnyObject]) -> String {
var components: [(String, String)] = []
for key in Array(parameters.keys).sort(<) {
let value: AnyObject! = parameters[key]
components += queryComponents(key, value)
}
return "&".join(components.map { "\($0)=\($1)" } as [String])
}
排序 key 這一步是刻意的:固定順序讓相同的參數永遠產生相同的字串,快取與除錯都因此變得可靠。
Alamofire.request(.GET, "https://httpbin.org/get", parameters: ["foo": "bar"])
.response { request, response, data, error in
print(request)
print(response)
print(error)
}
Alamofire 的網路操作全走非同步,不會阻塞主執行緒。response 是 Request 的擴充方法,傳入的閉包會在請求完成後被呼叫。
public func response(completionHandler: (NSURLRequest, NSHTTPURLResponse?, NSData?, NSError?) -> Void) -> Self {
return response(responseSerializer: Request.dataResponseSerializer(),
completionHandler: completionHandler)
}
再往下是最底層的泛型實作:
public func response<T: ResponseSerializerProtocol where T.SerializedObject == V>(
queue: dispatch_queue_t? = nil,
responseSerializer: T,
completionHandler: (NSURLRequest, NSHTTPURLResponse?, V?, NSError?) -> Void) -> Self {
delegate.queue.addOperationWithBlock {
let result: V?
let error: NSError?
(result, error) = responseSerializer.serializeResponse(
self.request, self.response, self.delegate.data)
dispatch_async(queue ?? dispatch_get_main_queue()) {
completionHandler(self.request, self.response, result,
self.delegate.error ?? error)
}
}
return self
}
三個設計值得留意:序列化被丟到 delegate.queue 背景執行,不佔用主體;回呼預設切回主執行緒,方便直接更新 UI;泛型約束 T.SerializedObject == V 讓回呼參數的型別由序列化器決定,編譯期就能擋掉型別不合的寫法。
response() — 原樣回傳 NSDataresponseString(encoding:) — 解成字串responseJSON(options:) — 解成 JSON 物件responsePropertyList(options:) — 解成 plist這四個方法最終都呼叫上面那個泛型函式,差別只在傳入的序列化器不同,因此回傳型別也跟著改變。
public enum Method: 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"
}
Alamofire.request(.GET, "https://httpbin.org/get", parameters: ["foo": "bar"])
// 結果:https://httpbin.org/get?foo=bar
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
四種編碼策略:
application/x-www-form-urlencoded。陣列會展開成 key[],字典正常配對。NSJSONSerialization 產生 JSON 字串,標頭改為 application/json。NSPropertyListSerialization,標頭為 application/x-plist。Alamofire.request(.POST, "https://httpbin.org/post",
parameters: parameters, encoding: .JSON)
// HTTP body: {foo: [1, 2, 3], bar: {baz: qux}}
標頭可以直接在全域 request 傳入。若某些請求需要更底層的控制(例如自訂 URLSessionConfiguration),就繞過 Manager 直接操作 NSURLSession,這樣產生的 task 自然帶著你設定的標頭。
快取相關 API 則是對 NSURLCache 的一層薄包裝:
sharedURLCache()/setSharedURLCache(_:)init(memoryCapacity:diskCapacity:diskPath:)cachedResponseForRequest(_:)/storeCachedResponse(_:forRequest:)removeAllCachedResponses()/removeCachedResponseForRequest(_:)currentDiskUsage/diskCapacity/currentMemoryUsage/memoryCapacity支援 File、Data、Stream、MultipartFormData 四種來源。
let fileURL = NSBundle.mainBundle().URLForResource("Default", withExtension: "png")
Alamofire.upload(.POST, URLString: "https://httpbin.org/post", file: fileURL!)
.progress { bytesWritten, totalBytesWritten, totalBytesExpectedToWrite in
print(totalBytesWritten)
}
.responseJSON { request, response, JSON, error in
print(JSON)
}
進度回報的運作方式是:progress 把閉包掛到 delegate 上,而 delegate 的 URLSession(...didSendBodyData:...) 被呼叫時,就把 totalUnitCount 與 completedUnitCount 寫進 NSProgress,再觸發閉包。
支援 Request 與 Resume Data 兩種來源。
Alamofire.download(.GET, URLString: "https://httpbin.org/stream/100",
destination: { (temporaryURL, response) in
if let directoryURL = NSFileManager.defaultManager()
.URLsForDirectory(.DocumentDirectory, inDomains: .UserDomainMask)[0]
as? NSURL {
let pathComponent = response.suggestedFilename
return directoryURL.URLByAppendingPathComponent(pathComponent!)
}
return temporaryURL
})
核心實作是 Manager 裡的 private 方法,根據來源型別分派到不同的 downloadTaskWith...:
private func download(downloadable: Downloadable,
destination: Request.DownloadFileDestination) -> Request {
var downloadTask: NSURLSessionDownloadTask!
switch downloadable {
case .Request(let request):
dispatch_sync(queue) { downloadTask = self.session.downloadTaskWithRequest(request) }
case .ResumeData(let resumeData):
dispatch_sync(queue) { downloadTask = self.session.downloadTaskWithResumeData(resumeData) }
}
let request = Request(session: session, task: downloadTask)
if let downloadDelegate = request.delegate as? Request.DownloadTaskDelegate {
downloadDelegate.downloadTaskDidFinishDownloadingToURL = { session, downloadTask, URL in
return destination(URL, downloadTask.response as! NSHTTPURLResponse)
}
}
delegate[request.delegate.task] = request.delegate
if startRequestsImmediately { request.resume() }
return request
}
若不想自己指定路徑,用內建的 suggestedDownloadDestination 就好,它會把檔案放進 Documents 目錄並以伺服器回傳的檔名命名。
Alamofire.request(.GET, "https://httpbin.org/get", parameters: ["foo": "bar"])
.validate(statusCode: 200..<300)
.validate(contentType: ["application/json"])
.response { _, _, _, error in
print(error)
}
validate 讓你能在回呼前先檢查狀態碼與 MIME 型別,不合規就直接產生錯誤:
public func validate(validation: Validation) -> Self {
delegate.queue.addOperationWithBlock {
if let response = self.response
where self.delegate.error == nil && !validation(self.request, response) {
self.delegate.error = NSError(domain: AlamofireErrorDomain,
code: -1,
userInfo: nil)
}
}
return self
}
讀完這條呼叫鏈,Alamofire 的架構其實很一致:全域函式負責收斂參數 → Manager 負責 session 與設定 → Request 負責單一請求的生命週期 → ResponseSerializer 負責把位元組轉成有用型別。每一層只做一件事,而串接點幾乎都是「傳一個閉包下去,完成後再呼叫回來」。
需要提醒的是,本文對應的是 Alamofire 3.x 時期的 Swift 2 語法。後續版本移除了 Manager,改用 SessionManager 與 AF/* 全域命名空間,ResponseSerializer 也改為 protocol 導向的 DataResponseSerializerProtocol。細節有變,分層思路則延續至今。