您的位置：首页 > 其它

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

2017-03-06 11:43 525 查看

本篇讲解参数编码的内容

前言

我们在开发中发的每一个请求都是通过

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

内容来自用户分享和网络整理，不保证内容的准确性，如有侵权内容，可联系管理员处理

标签：

相关文章推荐

新的分享

章节导航