本篇講解參數編碼的內容

前言

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

Alamofire中是這樣使用的:

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

  • 直接拼接到URL中
  • 通過request的httpBody傳值

• JSONEncoding 把參數字典編碼成JSONData后賦值給request的httpBody

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

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

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中。

由于出現了上邊所說的不同情況，因此考慮使用枚舉來對這些情況進行設計：

 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拆解后：

所以說，了解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) 簡書博客園