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协议的对象能够转换成URLRequestparameters参数，其类型为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源码解读系列(一)之概述和使用 简书博客园
