Alamofire源码解读系列(四)之参数编码(ParameterEncoding)

本篇讲解参数编码的内容

前言

我们在开发中发的每一个请求都是通过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拆解后：

组件名称	值
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) 简书博客园