Alamofire源碼解讀系列(四)之參數編碼(ParameterEncoding)

時間  2019-12-08
標籤 alamofire 源碼 解讀 系列 參數 編碼 parameterencoding 欄目 字符編碼 简体版
原文   原文鏈接

本篇講解參數編碼的內容html

前言

咱們在開發中發的每個請求都是經過URLRequest來進行封裝的，能夠經過一個URL生成URLRequest。那麼若是我有一個參數字典，這個參數字典又是如何從客戶端傳遞到服務器的呢？git

Alamofire中是這樣使用的:github

  • URLEncoding 和URL相關的編碼，有兩種編碼方式：json

    • 直接拼接到URL中
    • 經過request的httpBody傳值
  • JSONEncoding 把參數字典編碼成JSONData後賦值給request的httpBody

  • PropertyListEncoding把參數字典編碼成PlistData後賦值給request的httpBodyswift

那麼接下來就看看具體的實現過程是怎麼樣的？api

HTTPMethod

/// HTTP method definitions.
///
/// See https://tools.ietf.org/html/rfc7231#section-4.3
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"
}

上邊就是Alamofire中支持的HTTPMethod，這些方法的詳細定義，能夠看這篇文章：HTTP Method 詳細解讀(GET HEAD POST OPTIONS PUT DELETE TRACE CONNECT)數組

ParameterEncoding協議

/// A type used to define how a set of parameters are applied to a `URLRequest`.
public protocol ParameterEncoding {
    /// Creates a URL request by encoding parameters and applying them onto an existing request.
    ///
    /// - parameter urlRequest: The request to have parameters applied.
    /// - parameter parameters: The parameters to apply.
    ///
    /// - throws: An `AFError.parameterEncodingFailed` error if encoding fails.
    ///
    /// - returns: The encoded request.
    func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest
}

這個協議中只有一個函數，該函數須要兩個參數：服務器

  • urlRequest 該參數須要實現URLRequestConvertible協議，實現URLRequestConvertible協議的對象可以轉換成URLRequest
  • parameters 參數，其類型爲Parameters，也就是字典：public typealias Parameters = [String: Any]

該函數返回值類型爲URLRequest。經過觀察這個函數，咱們就明白了這個函數的目的就是把參數綁定到urlRequest之中，至於返回的urlRequest是否是以前的urlRequest，這個不必定，另外一個比較重要的是該函數會拋出異常，所以在本篇後邊的解讀中會說明該異常的來源。網絡

URLEncoding

咱們已經知道了URLEncoding就是和URL相關的編碼。當把參數編碼到httpBody中這種狀況是不受限制的，而直接編碼到URL中就會受限制，只有當HTTPMethod爲GET, HEAD and DELETE時才直接編碼到URL中。app

因爲出現了上邊所說的不一樣狀況，所以考慮使用枚舉來對這些狀況進行設計：

public enum Destination {
        case methodDependent, queryString, httpBody
    }

咱們對Destination的子選項給出解釋：

  • methodDependent 根據HTTPMethod自動判斷採起哪一種編碼方式
  • queryString 拼接到URL中
  • httpBody 拼接到httpBody中

在Alamofire源碼解讀系列(一)之概述和使用中咱們已經講解了如何使用Alamofire，在每一個請求函數的參數中，其中有一個參數就是編碼方式。咱們看看URLEncoding提供了那些初始化方法：

/// Returns a default `URLEncoding` instance.
    public static var `default`: URLEncoding { return URLEncoding() }

    /// Returns a `URLEncoding` instance with a `.methodDependent` destination.
    public static var methodDependent: URLEncoding { return URLEncoding() }

    /// Returns a `URLEncoding` instance with a `.queryString` destination.
    public static var queryString: URLEncoding { return URLEncoding(destination: .queryString) }

    /// Returns a `URLEncoding` instance with an `.httpBody` destination.
    public static var httpBody: URLEncoding { return URLEncoding(destination: .httpBody) }

    /// The destination defining where the encoded query string is to be applied to the URL request.
    public let destination: Destination

    // MARK: Initialization

    /// Creates a `URLEncoding` instance using the specified destination.
    ///
    /// - parameter destination: The destination defining where the encoded query string is to be applied.
    ///
    /// - returns: The new `URLEncoding` instance.
    public init(destination: Destination = .methodDependent) {
        self.destination = destination
    }

能夠看出，默認的初始化選擇的Destination是methodDependent，除了default這個單利外，又增長了其餘的三個。這裏須要注意一下，單利的寫法

public static var `default`: URLEncoding { return URLEncoding() }

如今已經可以建立URLEncoding了，是時候讓他實現ParameterEncoding協議裏邊的方法了。

/// Creates a URL request by encoding parameters and applying them onto an existing request.
    ///
    /// - parameter urlRequest: The request to have parameters applied.
    /// - parameter parameters: The parameters to apply.
    ///
    /// - throws: An `Error` if the encoding process encounters an error.
    ///
    /// - returns: The encoded request.
    public func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest {
        /// 獲取urlRequest
        var urlRequest = try urlRequest.asURLRequest()

        /// 若是參數爲nil就直接返回urlRequest
        guard let parameters = parameters else { return urlRequest }

        /// 把參數編碼到url的狀況
        if let method = HTTPMethod(rawValue: urlRequest.httpMethod ?? "GET"), encodesParametersInURL(with: method) {
            /// 取出url
            guard let url = urlRequest.url else {
                throw AFError.parameterEncodingFailed(reason: .missingURL)
            }

            /// 分解url
            if var urlComponents = URLComponents(url: url, resolvingAgainstBaseURL: false), !parameters.isEmpty {
           
                /// 把原有的url中的query百分比編碼後在拼接上編碼後的參數
                let percentEncodedQuery = (urlComponents.percentEncodedQuery.map { $0 + "&" } ?? "") + query(parameters) 
                urlComponents.percentEncodedQuery = percentEncodedQuery
                urlRequest.url = urlComponents.url
            }
        } else { /// 編碼到httpBody的狀況
            
            /// 設置Content-Type
            if urlRequest.value(forHTTPHeaderField: "Content-Type") == nil {
                urlRequest.setValue("application/x-www-form-urlencoded; charset=utf-8", forHTTPHeaderField: "Content-Type")
            }

            urlRequest.httpBody = query(parameters).data(using: .utf8, allowLossyConversion: false)
        }

        return urlRequest
    }

其實，這個函數的實現並不複雜，函數內的註釋部分就是這個函數的線索。固然，裏邊還用到了兩個外部函數：encodesParametersInURL和query，這兩個函數等會解釋。函數內還用到了URLComponents這個東東，能夠直接在這裏https://developer.apple.com/reference/foundation/nsurl獲取詳細信息。我再這裏就粗略的舉個例子來講明url的組成：

https://johnny:p4ssw0rd@www.example.com:443/script.ext;param=value?query=value#ref

這個url拆解後：

組件名稱 值
scheme https
user johnny
password p4ssw0rd
host www.example.com
port 443
path /script.ext
pathExtension ext
pathComponents ["/", "script.ext"]
parameterString param=value
query query=value
fragment ref

因此說，瞭解URL的組成頗有必要，只有對網絡請求有了詳細的瞭解，咱們才能去作網絡優化的一些事情。這些事情包括數據預加載，弱網處理等等。

上邊的代碼中出現了兩個額外的函數，咱們來看看這兩個函數。首先是encodesParametersInURL:

private func encodesParametersInURL(with method: HTTPMethod) -> Bool {
        switch destination {
        case .queryString:
            return true
        case .httpBody:
            return false
        default:
            break
        }

        switch method {
        case .get, .head, .delete:
            return true
        default:
            return false
        }
    }

這個函數的目的是判斷是否是要把參數拼接到URL之中，若是destination選的是queryString就返回true，若是是httpBody，就返回false，而後再根據method判斷，只有get，head，delete才返回true，其餘的返回false。

若是該函數返回的結果是true，那麼就把參數拼接到request的url中，不然拼接到httpBody中。

這裏簡單介紹下swift中的權限關鍵字：open, public, fileprivate, private:

  • open 該權限是最大的權限，容許訪問文件，同時容許繼承
  • public 容許訪問但不容許繼承
  • fileprivate 容許文件內訪問
  • private 只容許當前對象的代碼塊內部訪問

另一個函數是query,別看這個函數名很短，可是這個函數內部又嵌套了其餘的函數，並且這個函數纔是核心函數，它的主要功能是把參數處理成字符串，這個字符串也是作過編碼處理的：

private func query(_ parameters: [String: Any]) -> String {
        var components: [(String, String)] = []

        for key in parameters.keys.sorted(by: <) {
            let value = parameters[key]!
            components += queryComponents(fromKey: key, value: value)
        }

        return components.map { "\($0)=\($1)" }.joined(separator: "&")
    }

參數是一個字典，key的類型是String，但value的類型是any，也就是說value不必定是字符串，也有多是數組或字典，所以針對value須要作進一步的處理。咱們在寫代碼的過程當中，若是出現了這種特殊狀況，且是咱們已經考慮到了的狀況，咱們就應該考慮使用函數作專門的處理了。

上邊函數的總體思路是：

  • 寫一個數組，這個數組中存放的是元組數據，元組中存放的是key和字符串類型的value
  • 遍歷參數，對參數作進一步的處理，而後拼接到數組中
  • 進一步處理數組內部的元組數據，把元組內部的數據用=號拼接，而後用符號&把數組拼接成字符串

上邊函數中使用了一個額外函數queryComponents。這個函數的目的是處理value，咱們看看這個函數的內容：

/// Creates percent-escaped, URL encoded query string components from the given key-value pair using recursion.
    ///
    /// - parameter key:   The key of the query component.
    /// - parameter value: The value of the query component.
    ///
    /// - returns: The percent-escaped, URL encoded query string components.
    public func queryComponents(fromKey key: String, value: Any) -> [(String, String)] {
        var components: [(String, String)] = []

        if let dictionary = value as? [String: Any] {
            for (nestedKey, value) in dictionary {
                components += queryComponents(fromKey: "\(key)[\(nestedKey)]", value: value)
            }
        } else if let array = value as? [Any] {
            for value in array {
                components += queryComponents(fromKey: "\(key)[]", value: value)
            }
        } else if let value = value as? NSNumber {
            if value.isBool {
                components.append((escape(key), escape((value.boolValue ? "1" : "0"))))
            } else {
                components.append((escape(key), escape("\(value)")))
            }
        } else if let bool = value as? Bool {
            components.append((escape(key), escape((bool ? "1" : "0"))))
        } else {
            components.append((escape(key), escape("\(value)")))
        }

        return components
    }

該函數內部使用了遞歸。針對字典中的value的狀況作了以下幾種狀況的處理：

  • [String: Any] 若是value依然是字典，那麼調用自身，也就是作遞歸處理
  • [Any] 若是value是數組，遍歷後依然調用自身。把數組拼接到url中的規則是這樣的。假若有一個數組["a", "b", "c"],拼接後的結果是key[]="a"&key[]="b"&key[]="c"

  • NSNumber 若是value是NSNumber，要作進一步的判斷，判斷這個NSNumber是否是表示布爾類型。這裏引入了一個額外的函數escape,咱們立刻就會給出說明。

    extension NSNumber {
      fileprivate var isBool: Bool { return CFBooleanGetTypeID() == CFGetTypeID(self) }
  }
  • Bool 若是是Bool，轉義後直接拼接進數組

  • 其餘狀況，轉義後直接拼接進數組

上邊函數中的key已是字符串類型了，那麼爲何還要進行轉義的？這是由於在url中有些字符是不容許的。這些字符會干擾url的解析。按照RFC 3986的規定，下邊的這些字符必需要作轉義的：

:#[]@!$&'()*+,;=

?和/能夠不用轉義，可是在某些第三方的SDk中依然須要轉義，這個要特別注意。而轉義的意思就是百分號編碼。要了解百分號編碼的詳細內容，能夠看我轉債的這篇文章url 編碼（percentcode 百分號編碼）（轉載）

來看看這個escape函數：

/// Returns a percent-escaped string following RFC 3986 for a query string key or value.
    ///
    /// RFC 3986 states that the following characters are "reserved" characters.
    ///
    /// - General Delimiters: ":", "#", "[", "]", "@", "?", "/"
    /// - Sub-Delimiters: "!", "$", "&", "'", "(", ")", "*", "+", ",", ";", "="
    ///
    /// In RFC 3986 - Section 3.4, it states that the "?" and "/" characters should not be escaped to allow
    /// query strings to include a URL. Therefore, all "reserved" characters with the exception of "?" and "/"
    /// should be percent-escaped in the query string.
    ///
    /// - parameter string: The string to be percent-escaped.
    ///
    /// - returns: The percent-escaped string.
    public func escape(_ string: String) -> String {
        let generalDelimitersToEncode = ":#[]@" // does not include "?" or "/" due to RFC 3986 - Section 3.4
        let subDelimitersToEncode = "!$&'()*+,;="

        var allowedCharacterSet = CharacterSet.urlQueryAllowed
        allowedCharacterSet.remove(charactersIn: "\(generalDelimitersToEncode)\(subDelimitersToEncode)")

        var escaped = ""

        //==========================================================================================================
        //
        //  Batching is required for escaping due to an internal bug in iOS 8.1 and 8.2. Encoding more than a few
        //  hundred Chinese characters causes various malloc error crashes. To avoid this issue until iOS 8 is no
        //  longer supported, batching MUST be used for encoding. This introduces roughly a 20% overhead. For more
        //  info, please refer to:
        //
        //      - https://github.com/Alamofire/Alamofire/issues/206
        //
        //==========================================================================================================

        if #available(iOS 8.3, *) {
            escaped = string.addingPercentEncoding(withAllowedCharacters: allowedCharacterSet) ?? string
        } else {
            let batchSize = 50
            var index = string.startIndex

            while index != string.endIndex {
                let startIndex = index
                let endIndex = string.index(index, offsetBy: batchSize, limitedBy: string.endIndex) ?? string.endIndex
                let range = startIndex..<endIndex

                let substring = string.substring(with: range)

                escaped += substring.addingPercentEncoding(withAllowedCharacters: allowedCharacterSet) ?? substring

                index = endIndex
            }
        }

        return escaped
    }

該函數的思路也很簡單，使用了系統自帶的函數來進行百分號編碼，值得注意的是，若是系統小於8.3須要作特殊的處理，正好在這個處理中，咱們研究一下swift中Range的用法。

對於一個string,他的範圍是從string.startIndex到string.endIndex的。經過public func index(_ i: String.Index, offsetBy n: String.IndexDistance, limitedBy limit: String.Index) -> String.Index?函數能夠取一個範圍，這裏中重要的就是index的概念，而後經過startIndex..<endIndex就生成了一個Range，利用這個Range就能截取字符串了。關於Range更多的用法，請參考蘋果官方文檔。

到這裏，URLEncoding的所有內容就分析完畢了，咱們把不一樣的功能劃分紅不一樣的函數，這種作法最大的好處就是咱們可使用單獨的函數作獨立的事情。我徹底可使用escape這個函數轉義任何字符串。

JSONEncoding

JSONEncoding的主要做用是把參數以JSON的形式編碼到request之中，固然是經過request的httpBody進行賦值的。JSONEncoding提供了兩種處理函數，一種是對普通的字典參數進行編碼，另外一種是對JSONObject進行編碼，處理這兩種狀況的函數基本上是相同的，在下邊會作出統一的說明。

咱們先看看初始化方法：

/// Returns a `JSONEncoding` instance with default writing options.
    public static var `default`: JSONEncoding { return JSONEncoding() }

    /// Returns a `JSONEncoding` instance with `.prettyPrinted` writing options.
    public static var prettyPrinted: JSONEncoding { return JSONEncoding(options: .prettyPrinted) }

    /// The options for writing the parameters as JSON data.
    public let options: JSONSerialization.WritingOptions

    // MARK: Initialization

    /// Creates a `JSONEncoding` instance using the specified options.
    ///
    /// - parameter options: The options for writing the parameters as JSON data.
    ///
    /// - returns: The new `JSONEncoding` instance.
    public init(options: JSONSerialization.WritingOptions = []) {
        self.options = options
    }

這裏邊值得注意的是JSONSerialization.WritingOptions,也就是JSON序列化的寫入方式。WritingOptions是一個結構體，系統提供了一個選項：prettyPrinted,意思是更好的打印效果。

接下來看看下邊的兩個函數：

/// Creates a URL request by encoding parameters and applying them onto an existing request.
    ///
    /// - parameter urlRequest: The request to have parameters applied.
    /// - parameter parameters: The parameters to apply.
    ///
    /// - throws: An `Error` if the encoding process encounters an error.
    ///
    /// - returns: The encoded request.
    public func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest {
        var urlRequest = try urlRequest.asURLRequest()

        guard let parameters = parameters else { return urlRequest }

        do {
            let data = try JSONSerialization.data(withJSONObject: parameters, options: options)

            if urlRequest.value(forHTTPHeaderField: "Content-Type") == nil {
                urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
            }

            urlRequest.httpBody = data
        } catch {
            throw AFError.parameterEncodingFailed(reason: .jsonEncodingFailed(error: error))
        }

        return urlRequest
    }

    /// Creates a URL request by encoding the JSON object and setting the resulting data on the HTTP body.
    ///
    /// - parameter urlRequest: The request to apply the JSON object to.
    /// - parameter jsonObject: The JSON object to apply to the request.
    ///
    /// - throws: An `Error` if the encoding process encounters an error.
    ///
    /// - returns: The encoded request.
    public func encode(_ urlRequest: URLRequestConvertible, withJSONObject jsonObject: Any? = nil) throws -> URLRequest {
        var urlRequest = try urlRequest.asURLRequest()

        guard let jsonObject = jsonObject else { return urlRequest }

        do {
            let data = try JSONSerialization.data(withJSONObject: jsonObject, options: options)

            if urlRequest.value(forHTTPHeaderField: "Content-Type") == nil {
                urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
            }

            urlRequest.httpBody = data
        } catch {
            throw AFError.parameterEncodingFailed(reason: .jsonEncodingFailed(error: error))
        }

        return urlRequest
    }

第一個函數實現了ParameterEncoding協議，第二個參數做爲擴展，函數中最核心的內容是把參數變成Data類型，而後給httpBody賦值，須要注意的是異常處理。

PropertyListEncoding

PropertyListEncoding的處理方式和JSONEncoding的差很少，爲了節省篇幅，就不作出解答了。直接上源碼：

/// Uses `PropertyListSerialization` to create a plist representation of the parameters object, according to the
/// associated format and write options values, which is set as the body of the request. The `Content-Type` HTTP header
/// field of an encoded request is set to `application/x-plist`.
public struct PropertyListEncoding: ParameterEncoding {

    // MARK: Properties

    /// Returns a default `PropertyListEncoding` instance.
    public static var `default`: PropertyListEncoding { return PropertyListEncoding() }

    /// Returns a `PropertyListEncoding` instance with xml formatting and default writing options.
    public static var xml: PropertyListEncoding { return PropertyListEncoding(format: .xml) }

    /// Returns a `PropertyListEncoding` instance with binary formatting and default writing options.
    public static var binary: PropertyListEncoding { return PropertyListEncoding(format: .binary) }

    /// The property list serialization format.
    public let format: PropertyListSerialization.PropertyListFormat

    /// The options for writing the parameters as plist data.
    public let options: PropertyListSerialization.WriteOptions

    // MARK: Initialization

    /// Creates a `PropertyListEncoding` instance using the specified format and options.
    ///
    /// - parameter format:  The property list serialization format.
    /// - parameter options: The options for writing the parameters as plist data.
    ///
    /// - returns: The new `PropertyListEncoding` instance.
    public init(
        format: PropertyListSerialization.PropertyListFormat = .xml,
        options: PropertyListSerialization.WriteOptions = 0)
    {
        self.format = format
        self.options = options
    }

    // MARK: Encoding

    /// Creates a URL request by encoding parameters and applying them onto an existing request.
    ///
    /// - parameter urlRequest: The request to have parameters applied.
    /// - parameter parameters: The parameters to apply.
    ///
    /// - throws: An `Error` if the encoding process encounters an error.
    ///
    /// - returns: The encoded request.
    public func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest {
        var urlRequest = try urlRequest.asURLRequest()

        guard let parameters = parameters else { return urlRequest }

        do {
            let data = try PropertyListSerialization.data(
                fromPropertyList: parameters,
                format: format,
                options: options
            )

            if urlRequest.value(forHTTPHeaderField: "Content-Type") == nil {
                urlRequest.setValue("application/x-plist", forHTTPHeaderField: "Content-Type")
            }

            urlRequest.httpBody = data
        } catch {
            throw AFError.parameterEncodingFailed(reason: .propertyListEncodingFailed(error: error))
        }

        return urlRequest
    }
}

JSONStringArrayEncoding

這是Alamofire種對字符串數組編碼示例。原理也很簡單，直接上代碼：

public struct JSONStringArrayEncoding: ParameterEncoding {
    public let array: [String]
    
    public init(array: [String]) {
        self.array = array
    }
    
    public func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest {
        var urlRequest = urlRequest.urlRequest
        
        let data = try JSONSerialization.data(withJSONObject: array, options: [])
        
        if urlRequest!.value(forHTTPHeaderField: "Content-Type") == nil {
            urlRequest!.setValue("application/json", forHTTPHeaderField: "Content-Type")
        }
        
        urlRequest!.httpBody = data
        
        return urlRequest!
    }
}

總結

只有瞭解了某個功能的內部實現原理，咱們才能更好的使用這個功能。沒毛病。

因爲知識水平有限，若有錯誤，還望指出

連接

Alamofire源碼解讀系列(一)之概述和使用 簡書博客園

Alamofire源碼解讀系列(二)之錯誤處理(AFError) 簡書博客園

Alamofire源碼解讀系列(三)之通知處理(Notification) 簡書博客園

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程