
本文為投稿文章
原文:Swift 網路庫 Alamofire 源碼分析
本文就來分析 Swift 網路庫 Alamofire 的實作源碼(基於版本 3.1.1)。
目錄結構

先來看源碼結構。Source 目錄下包含 Alamofire.swift,主要負責對外暴露一些常用呼叫介面;Core 資料夾放的是核心功能的實作;而 Feature 則是在 Core 基礎上包裝出我們更常用、更方便的功能。
如果你只想知道怎麼使用這個庫,基本上只要了解 Alamofire.swift 以及 Core/ResponseSerialization.swift 這兩個檔案就夠了。
通用工具函式或類別
在整體分析前,先說明庫中一些通用的東西:
Error.swift 用於產生 NSError 錯誤物件,包含一些常見的網路錯誤,如資料錯誤、伺服器狀態錯誤、解析序列錯誤等。
ParameterEncoding.swift 處理網路請求時的 HTTP content-type,如 application/x-www-form-urlencoded; charset=utf-8、application/json 等。
Result.swift 是網路回傳結果,一個列舉,包含 Success 與 Failure;成功時帶有資料,失敗時帶有錯誤資訊,供後續的 response 使用。
Alamofire.swift 中定義的兩個 protocol:URLStringConvertible 方便 NSURLRequest 與 String 之間的轉換,以及 URLRequestConvertible。
整體流程圖

上圖是 Alamofire 的網路請求流程圖,後文將依此圖,對一次網路請求從開始到結束的整體流程做分析。由於 NSURLSession 包含 data、upload、download 等幾種不同的 task,本篇主要跟蹤 data 流程,其餘兩者的原理相同,只是型別不同。
依使用文件,若要發起一個 GET 請求、伺服器回傳 JSON 資料,只需使用如下方法:
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.request 做了什麼,它呼叫了 Manager 類別中的 request 方法:
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 ) }Manager.swift
public class Manager:Manager 類別有個單例方法,該方法產生的 NSURLSession 的 configuration 為系統預設的 NSURLSessionConfiguration.defaultSessionConfiguration(),並把 session 的 delegate 設為自己的成員變數 delegate: SessionDelegate。這個 delegate 既肩負 session 的回呼代理,也肩負 task 回呼代理的分派調度——它會依不同的 task 類別,把任務分配給對應的 delegate 物件處理。上一步中 request 的對應方法為:
public func request( method: Method, _ URLString: URLStringConvertible, parameters: [String: AnyObject]? = nil, encoding: ParameterEncoding = .URL, headers: [String: String]? = nil) -> Request { let mutableURLRequest = URLRequest(method, URLString, headers: headers) let encodedURLRequest = encoding.encode(mutableURLRequest, parameters: parameters).0 return request(encodedURLRequest) } public func request(URLRequest: URLRequestConvertible) -> Request { var dataTask: NSURLSessionDataTask! dispatch_sync(queue) { dataTask = self.session.dataTaskWithRequest(URLRequest.URLRequest) } let request = Request(session: session, task: dataTask) delegate[request.delegate.task] = request.delegate if startRequestsImmediately { request.resume() } return request } 這裡會依 URLRequest 產生一個 dataTask(為避免多執行緒問題,產生過程都在同一執行緒中進行),同時由 session 與 dataTask 產生一個 Request 物件(這裡的 request 並非我們常用的 NSURLRequest,而是 Alamofire 中封裝的 Request 物件)並回傳。此方法中的 delegate[request.delegate.task] = request.delegate,指定了這個 dataTask 對應的 delegate 回呼處理類別,下面會講到。
public final class SessionDelegate:此類別被宣告為 final,不允許被繼承。
public final class SessionDelegate: NSObject, NSURLSessionDelegate, NSURLSessionTaskDelegate, NSURLSessionDataDelegate, NSURLSessionDownloadDelegate { private var subdelegates: [Int: Request.TaskDelegate] = [:] private let subdelegateQueue = dispatch_queue_create(nil, DISPATCH_QUEUE_CONCURRENT) private var subscript(task: NSURLSessionTask) -> Request.TaskDelegate? { get { var subdelegate: Request.TaskDelegate? dispatch_sync(subdelegateQueue) { subdelegate = self.subdelegates[task.taskIdentifier] } return subdelegate } set { dispatch_barrier_async(subdelegateQueue) { self.subdelegates[task.taskIdentifier] = newValue } } }可以看到,它實作了 session 以及三種不同 task 的代理。此類別實作了 subscript 的下標功能,讓它能依不同 task id 更方便地呼叫對應的 delegate 處理方法。
實際上是透過 subdelegate 陣列來實現,裡面每個元素都是一個字典,字典的 key 為 taskIdentifier、value 為真正要處理的 delegate 類別。同樣為了避免多執行緒問題,這裡用 dispatch_barrier_async 來確保執行緒安全。
為了讓使用更靈活,這個類別還實作了類似攔截的機制,讓你能自訂 session 的回呼。身為一個類庫,當然不能因為自己的一些特殊用途就隨意改動源碼(除非你打算自己維護一套),所以它為每個 delegate 方法都預留了自訂的實作。若有這方面需求,可以參考這種做法:
public override func respondsToSelector(selector: Selector) -> Bool { switch selector { case "URLSession:didBecomeInvalidWithError:": return sessionDidBecomeInvalidWithError != nil case "URLSession:didReceiveChallenge:completionHandler:": return sessionDidReceiveChallenge != nil case "URLSessionDidFinishEventsForBackgroundURLSession:": return sessionDidFinishEventsForBackgroundURLSession != nil case "URLSession:task:willPerformHTTPRedirection:newRequest:completionHandler:": return taskWillPerformHTTPRedirection != nil case "URLSession:dataTask:didReceiveResponse:completionHandler:": return dataTaskDidReceiveResponse != nil default: return self.dynamicType.instancesRespondToSelector(selector) } }舉例來說,若我想對 sessionDidReceiveChallenge 自訂,只需實作:
Manager.sharedInstance.delegate.sessionDidReceiveChallenge = {(session, challenge) -> (NSURLSessionAuthChallengeDisposition, NSURLCredential) in let disposition: NSURLSessionAuthChallengeDisposition = .PerformDefaultHandling let credential = NSURLCredential(user: "user", password: "password", persistence: .None) return (disposition, credential) }就完成了對 challenge 的自訂。
Request.swift
public class Request:在初始化時依不同 task 產生不同的 delegate 處理類別,每個類別都對應各自的回呼函式。
init(session: NSURLSession, task: NSURLSessionTask) { self.session = session switch task { case is NSURLSessionUploadTask: self.delegate = UploadTaskDelegate(task: task) case is NSURLSessionDataTask: self.delegate = DataTaskDelegate(task: task) case is NSURLSessionDownloadTask: self.delegate = DownloadTaskDelegate(task: task) default: self.delegate = TaskDelegate(task: task) } }public class TaskDelegate 及其子類 DataTaskDelegate、UploadTaskDelegate、DownloadTaskDelegate:
這些類別才是真正處理 task 對應的回呼任務,負責存放 data、error、progress 等資訊,以及 task 的 suspend、resume、cancel 等基本操作。
其中成員變數 public let queue: NSOperationQueue 是相當關鍵的一環,後續 response 的處理都在它上面進行。它被初始化後 suspended 會被設為 true,只有當 task 完成之後(func URLSession(session: NSURLSession, task: NSURLSessionTask, didCompleteWithError error: NSError?))才被設為 false,此時加在它內部的 operation(也就是 response 的序列化)才會真正執行,解析完畢後再呼叫回呼 completionHandler。
Response.swift
public struct Response:一個泛型的 struct,它的型別與一開始提到的 result 對應型別一致,都包含了真正的請求結果資料 value 或 error。例如 string、data、json 就是 result 當中 value 的值。
public struct Response{ /// The URL request sent to the server. public let request: NSURLRequest? /// The server's response to the URL request. public let response: NSHTTPURLResponse? /// The data returned by the server. public let data: NSData? /// The result of response serialization. public let result: Result /** Initializes the `Response` instance with the specified URL request, URL response, server data and response serialization result. - parameter request: The URL request sent to the server. - parameter response: The server's response to the URL request. - parameter data: The data returned by the server. - parameter result: The result of response serialization. - returns: the new `Response` instance. */ public init(request: NSURLRequest?, response: NSHTTPURLResponse?, data: NSData?, result: Result) { self.request = request self.response = response self.data = data self.result = result } }ResponseSerialization.swift
public protocol ResponseSerializerType:序列化的協議,定義了對 response 序列化的協議函式。這裡有個值得學習的地方是對 typealias 的運用,可參考 typealias 與泛型介面。
public struct ResponseSerializer:實作了 ResponseSerializerType 協議,除了實作協議裡的函式,還要實作裡面的 typealias 定義。
extension Request:對 Request 序列化的擴充實作。比如我們一開始的 responseJson 函式,透過呼叫 JSONResponseSerializer 回傳一個序列化物件;此函式中用到了 Swift 的 do-catch 機制來擷取與處理異常,最後統一呼叫 response 函式。這裡就是在前面提到的 request.delegate 的 operationQueue 中加入一個執行序列化的 operation,完成後把封裝好的 response 物件透過 block 回呼傳出。
public static func JSONResponseSerializer( options options: NSJSONReadingOptions = .AllowFragments) -> ResponseSerializer { return ResponseSerializer { _, response, data, error in guard error == nil else { return .Failure(error!) } if let response = response where response.statusCode == 204 { return .Success(NSNull()) } guard let validData = data where validData.length > 0 else { let failureReason = "JSON could not be serialized. Input data was nil or zero length." let error = Error.errorWithCode(.JSONSerializationFailed, failureReason: failureReason) return .Failure(error) } do { let JSON = try NSJSONSerialization.JSONObjectWithData(validData, options: options) return .Success(JSON) } catch { return .Failure(error as NSError) } } } public func responseJSON( options options: NSJSONReadingOptions = .AllowFragments, completionHandler: Response-> Void) -> Self { return response( responseSerializer: Request.JSONResponseSerializer(options: options), completionHandler: completionHandler ) } public func response( queue queue: dispatch_queue_t? = nil, responseSerializer: T, completionHandler: Response-> Void) -> Self { delegate.queue.addOperationWithBlock { let result = responseSerializer.serializeResponse( self.request, self.response, self.delegate.data, self.delegate.error ) dispatch_async(queue ?? dispatch_get_main_queue()) { let response = Response( request: self.request, response: self.response, data: self.delegate.data, result: result ) completionHandler(response) } } return self } 至此,一次完整的請求流程就走完了,upload 與 download 的流程也一樣。
總結:
Alamofire 是個很好用的網路庫,使用起來相當方便。不過若專案有一定規模與複雜度,建議還是依自身需求做一層封裝。
因為它是基於 NSURLSession 實作的網路請求,如果你有多個併發請求(例如下載多個檔案),直接發出 10 個請求,但你只想支援最大 2 個併發,那麼 NSURLSession 的 timeoutIntervalForRequest 與 timeoutIntervalForResource 並無法滿足需求,你必須自己用 operation queue 來實作。
參考資料:
Swift Generics Tutorial:這篇文章把泛型講得很好,只是範例專案可能不是 Swift 2.0 的,稍微改一下就能跑。
typealias 與泛型介面