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

96
老马的春天
0.3 2017.03.06 11:44* 字数 2568

本篇讲解参数编码的内容

前言

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

其实,这个函数的实现并不复杂,函数内的注释部分就是这个函数的线索。当然,里边还用到了两个外部函数:encodesParametersInURLquery,这两个函数等会解释。函数内还用到了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.startIndexstring.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) 简书博客园

随笔
Web note ad 1