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) 简书博客园