Alamofire源码解读系列(十二)之请求(Request)

本篇是Alamofire中的请求抽象层的讲解

前言

在Alamofire中,围绕着Request,设计了很多额外的特性,这也恰恰表明,Request是所有请求的基础部分和发起点。这无疑给我们一个Request很复杂的想法。但看了Alamofire中Request.swift中的代码,Request被设计的又是如此的简单,这就是为什么这些顶级框架如此让人喜爱的原因。

在后续的文章中,我会单独写一篇Swift中协议的使用技巧,在Alamofire源码解读系列(一)之概述和使用这篇的Alamofire高级用法中,我根据Alamofire官方文档做了一些补充,其中涉及到了URLConvertible和URLRequestConvertible的高级用法,在本篇中同样出现了3个协议:

  • RequestAdapter 请求适配器,目的是自定义修改请求,一个典型的例子是为每一个请求调价Token请求头
  • RequestRetrier 请求重试器, 目的是控制请求的重试机制,一个典型的例子是当某个特殊的请求失败后,是否重试。
  • TaskConvertible task转换器,目的是把task装换成特定的类型,在Alamofire中有4中task:Data/Download/Upload/Stream

有一点需要特别说明的是,在使用Alamofire的高级用法时,需要操作SessionManager这个类。

请求过程

明白Alamofire中一个请求的过程,是非常有必要的。先看下边的代码:

Alamofire.request("https://httpbin.org/get")

上边的代码是最简单的一个请求,我们看看Alamofire.request中究竟干了什么?

@discardableResult
public func request(
    _ url: URLConvertible,
    method: HTTPMethod = .get,
    parameters: Parameters? = nil,
    encoding: ParameterEncoding = URLEncoding.default,
    headers: HTTPHeaders? = nil)
    -> DataRequest
{
    return SessionManager.default.request(
        url,
        method: method,
        parameters: parameters,
        encoding: encoding,
        headers: headers
    )
}

该函数内部调用了SessionManager的request方法,这说明请求的第一个发起点来自SessionManager,Alamofire.swift该文件是最上层的封装,紧邻其下的就是SessionManager.swift。接下来我们再看看SessionManager.default.request做了什么?

@discardableResult
    open func request(
        _ url: URLConvertible,
        method: HTTPMethod = .get,
        parameters: Parameters? = nil,
        encoding: ParameterEncoding = URLEncoding.default,
        headers: HTTPHeaders? = nil)
        -> DataRequest
    {
        var originalRequest: URLRequest?
		/// 在这里计算出可能出现的额错误的类型
        /// 1.url 如果不能被转成URL被抛出一个error
        /// 2.originalRequest不能转换为URLRequest会抛出error
        do {
            originalRequest = try URLRequest(url: url, method: method, headers: headers)
            let encodedURLRequest = try encoding.encode(originalRequest!, with: parameters)
            return request(encodedURLRequest)
        } catch {
            return request(originalRequest, failedWith: error)
        }
    }

上边的函数内部创建了一个Request对象,然后把参数编码进这个Request中,之后又调用了内部的一个request函数,函数的参数就是上边的Request对象。我们就绪看看这个request函数做了什么?

    open func request(_ urlRequest: URLRequestConvertible) -> DataRequest {
        var originalRequest: URLRequest?

        do {
            originalRequest = try urlRequest.asURLRequest()
            /// 这里需要注意的是Requestable并不是DataRequest的一个属性,前边是没有加let/var的,所以可以通过DataRequest.Requestable来操作
            let originalTask = DataRequest.Requestable(urlRequest: originalRequest!)

            let task = try originalTask.task(session: session, adapter: adapter, queue: queue)
            let request = DataRequest(session: session, requestTask: .data(originalTask, task))

            delegate[task] = request

            if startRequestsImmediately { request.resume() }

            return request
        } catch {
            return request(originalRequest, failedWith: error)
        }
    }

注意,上边的函数是一个open函数,因此可以使用SessionManager.request来发起请求,不过参数是_ urlRequest: URLRequestConvertible

URLRequestConvertible协议的目的是对URLRequest进行自定义的转换,因此,在获得转换后的URLRequest后,需要用URLRequest生成task,这样才能发起网络请求,在Alamofire中,但凡是request开头的函数,默认的都是DataRequest类型,现在有了URLRequest还不够,还需要检测她能否生成与之相对应的task。

在上边的函数中,用到了DataRequest.Requestable,Requestable其实一个结构体,他实现了TaskConvertible协议,因此,它能够用URLRequest生成与之相对应的task。接下来就初始化DataRequest,然后真正的开始发起请求。

我们总结一下这个过程:

明白了上边的过程,再回过头来看Request.swift也就是本篇的内容就简单多了,就下边几个目的:

  • 创建DataRequest/DownloadRequest/UploadRequest/StreamRequest
  • 发起请求

Request

有很多二次封装的网络框架中,一般都有这么一个Request类,用于发送网络请求,接受response,关联服务器返回的数据并且管理task。Alamofire中的Request同样主要实现上边的任务。

Request作为DataRequest、DownloadRequest、UploadRequest、StreamRequest的基类,我们一起来看看它有哪些属性:

/// The delegate for the underlying task.
    /// 由于某个属性是通过另一个属性来setter和getter的,因此建议加一个锁
    open internal(set) var delegate: TaskDelegate {
        get {
            taskDelegateLock.lock() ; defer { taskDelegateLock.unlock() }
            return taskDelegate
        }
        set {
            taskDelegateLock.lock() ; defer { taskDelegateLock.unlock() }
            taskDelegate = newValue
        }
    }

    /// The underlying task.
    open var task: URLSessionTask? { return delegate.task }

    /// The session belonging to the underlying task.
    open let session: URLSession

    /// The request sent or to be sent to the server.
    open var request: URLRequest? { return task?.originalRequest }

    /// The response received from the server, if any.
    open var response: HTTPURLResponse? { return task?.response as? HTTPURLResponse }

    /// The number of times the request has been retried.
    open internal(set) var retryCount: UInt = 0

    let originalTask: TaskConvertible?

    var startTime: CFAbsoluteTime?
    var endTime: CFAbsoluteTime?

    var validations: [() -> Void] = []

    private var taskDelegate: TaskDelegate
    private var taskDelegateLock = NSLock()

这些属性没什么好说的,我们就略过这些内容,Request的初始化方法,有点意思,我们先看看代码:

init(session: URLSession, requestTask: RequestTask, error: Error? = nil) {
        self.session = session

        switch requestTask {
        case .data(let originalTask, let task):
            taskDelegate = DataTaskDelegate(task: task)
            self.originalTask = originalTask
        case .download(let originalTask, let task):
            taskDelegate = DownloadTaskDelegate(task: task)
            self.originalTask = originalTask
        case .upload(let originalTask, let task):
            taskDelegate = UploadTaskDelegate(task: task)
            self.originalTask = originalTask
        case .stream(let originalTask, let task):
            taskDelegate = TaskDelegate(task: task)
            self.originalTask = originalTask
        }

        delegate.error = error
        delegate.queue.addOperation { self.endTime = CFAbsoluteTimeGetCurrent() }
    }

要想发起一个请求,有一个task就足够了,在上边的方法中传递过来的session主要用于CustomStringConvertibleCustomDebugStringConvertible这两个协议的实现方法中获取特定的数据。

这里有一点小提示,在创建自定义的类的时候,实现上边这两个协议,通过打印,能够进行快速的调试。

上边方法中第二个参数是requestTask,它是一个枚举类型,我们看一下:

enum RequestTask {
        case data(TaskConvertible?, URLSessionTask?)
        case download(TaskConvertible?, URLSessionTask?)
        case upload(TaskConvertible?, URLSessionTask?)
        case stream(TaskConvertible?, URLSessionTask?)
    }

在swift中枚举不仅仅用来区分不同的选项,更强大的是为每个选项绑定的数据。大家仔细想一下,在初始化Request的时候,只需要传递requestTask这个枚举值,我们就得到了两个重要的数据:Request的类型和相对应的task。这一变成手法的运用,大大提高了代码的质量。

RequestTask枚举中和选项绑定的数据有两个,TaskConvertible表示原始的对象,该对象实现了TaskConvertible协议,能够转换成task。URLSessionTask是原始对象转换后的task。因此衍生出一种高级使用方法的可能性,可以自定义一个类,实现TaskConvertible协议,就能够操纵task的转换过程,很灵活。

delegate.queue.addOperation { self.endTime = CFAbsoluteTimeGetCurrent() }

上边的这一行代码。给代理的queue添加了一个操作,队列是先进先出原则,但是可以通过isSuspended暂停队列内部的操作,下边是一个例子演示:

let queue = { () -> OperationQueue in 
    let operationQueue = OperationQueue()
    
    operationQueue.maxConcurrentOperationCount = 1
    operationQueue.isSuspended = true
    operationQueue.qualityOfService = .utility
    
    return operationQueue
}()

queue.addOperation {
    print("1")
}

queue.addOperation {
    print("2")
}

queue.addOperation {
    print("3")
}

queue.isSuspended = false

打印结果:

1
2
3

队列提供了强大的功能,了解队列的知识点非常有必要,有很大的一种可能性,也许某个问题卡住了,用队列能够很轻松的解决。有兴趣可以看看我模仿SDWebImage写的下载器MCDownloader(iOS下载器)说明书

处理网络请求,就必须要面对安全的问题,为了解决数据传输安全问题,到目前为止,已经出现了很多种解决方式。想了解这方面的知识,可以去看<<HTTP权威指南>>

Alamofire源码解读系列(一)之概述和使用中的Alamofire高级使用技巧部分。

 /// Associates an HTTP Basic credential with the request.
    ///
    /// - parameter user:        The user.
    /// - parameter password:    The password.
    /// - parameter persistence: The URL credential persistence. `.ForSession` by default.
    ///
    /// - returns: The request.
    /// 这里需要注意一点,persistence表示持久性,可以点击去查看详细说明
    @discardableResult
    open func authenticate(
        user: String,
        password: String,
        persistence: URLCredential.Persistence = .forSession)
        -> Self
    {
        let credential = URLCredential(user: user, password: password, persistence: persistence)
        return authenticate(usingCredential: credential)
    }

    /// Associates a specified credential with the request.
    ///
    /// - parameter credential: The credential.
    ///
    /// - returns: The request.
    @discardableResult
    open func authenticate(usingCredential credential: URLCredential) -> Self {
        delegate.credential = credential
        return self
    }

上边的这两个函数能够处理请求中的验证问题,可以用来应对用户密码和证书验证。

  /// Returns a base64 encoded basic authentication credential as an authorization header tuple.
    ///
    /// - parameter user:     The user.
    /// - parameter password: The password.
    ///
    /// - returns: A tuple with Authorization header and credential value if encoding succeeds, `nil` otherwise.
    open static func authorizationHeader(user: String, password: String) -> (key: String, value: String)? {
        guard let data = "\(user):\(password)".data(using: .utf8) else { return nil }

        let credential = data.base64EncodedString(options: [])

        return (key: "Authorization", value: "Basic \(credential)")
    }

这个方法是一个辅助函数,某些服务器可能需要把用户名和密码拼接到请求头中,那么可以使用这个函数来实现。

我们对一个请求的操作有下边3中可能:

  • resume 唤醒该请求,这个非常简单,函数中做了3件事:记录开始时间,唤醒task,发通知。

      /// Resumes the request.
          open func resume() {
              guard let task = task else { delegate.queue.isSuspended = false ; return }
      
              if startTime == nil { startTime = CFAbsoluteTimeGetCurrent() }
      
              task.resume()
      
              NotificationCenter.default.post(
                  name: Notification.Name.Task.DidResume,
                  object: self,
                  userInfo: [Notification.Key.Task: task]
              )
          }
    
  • suspend 暂停

        /// Suspends the request.
          open func suspend() {
              guard let task = task else { return }
      
              task.suspend()
      
              NotificationCenter.default.post(
                  name: Notification.Name.Task.DidSuspend,
                  object: self,
                  userInfo: [Notification.Key.Task: task]
              )
          }
    
  • cancel 取消

      /// Cancels the request.
          open func cancel() {
              guard let task = task else { return }
      
              task.cancel()
      
              NotificationCenter.default.post(
                  name: Notification.Name.Task.DidCancel,
                  object: self,
                  userInfo: [Notification.Key.Task: task]
              )
          }
    

Request中对CustomDebugStringConvertible和CustomStringConvertible的实现,我们就不做太多介绍了,有两点需要注意:

  1. 类似像urlCredentialStorage, httpCookieStorage这种带有Storage字段的对象,需要仔细研究一下这种代码设计的规律。

  2. 下边这一小段代码正好提现了swift的优雅之处,需要记住:

     for (field, value) in headerFields where field != "Cookie" {
                     headers[field] = value
                 }
    

TaskConvertible

TaskConvertible协议给了给了我们转换task的能力,任何实现了该协议的对象,都表示能够转换成一个task。我们都知道DataRequest,DownloadRequest,UploadRequest,StreamRequest都继承自Request,最终应该是通过TaskConvertible协议来把一个URLRequest转换成对应的task。

而Alamofire的Request的设计中,采用struct或者enum来实现这个协议,我们来看看这些实现;

DataRequest:

  struct Requestable: TaskConvertible {
        let urlRequest: URLRequest

        func task(session: URLSession, adapter: RequestAdapter?, queue: DispatchQueue) throws -> URLSessionTask {
            do {
                let urlRequest = try self.urlRequest.adapt(using: adapter)
                return queue.sync { session.dataTask(with: urlRequest) }
            } catch {
                throw AdaptError(error: error)
            }
        }
    }

DownloadRequest:

  enum Downloadable: TaskConvertible {
        case request(URLRequest)
        case resumeData(Data)

        func task(session: URLSession, adapter: RequestAdapter?, queue: DispatchQueue) throws -> URLSessionTask {
            do {
                let task: URLSessionTask

                switch self {
                case let .request(urlRequest):
                    let urlRequest = try urlRequest.adapt(using: adapter)
                    task = queue.sync { session.downloadTask(with: urlRequest) }
                case let .resumeData(resumeData):
                    task = queue.sync { session.downloadTask(withResumeData: resumeData) }
                }

                return task
            } catch {
                throw AdaptError(error: error)
            }
        }
    }

如果task的类型是下载,会出现两种情况,一种是直接通过URLRequest生成downloadTask,另一种是根据已有的数据恢复成downloadTask。我们之前已经讲过了,下载失败后会有resumeData。里边保存了下载信息,这里就不提了。总之,上边这个enum给我们提供了两种不同的方式来生成downloadTask。

这种代码的设计值得学习。

UploadRequest:

 enum Uploadable: TaskConvertible {
        case data(Data, URLRequest)
        case file(URL, URLRequest)
        case stream(InputStream, URLRequest)

        func task(session: URLSession, adapter: RequestAdapter?, queue: DispatchQueue) throws -> URLSessionTask {
            do {
                let task: URLSessionTask

                switch self {
                case let .data(data, urlRequest):
                    let urlRequest = try urlRequest.adapt(using: adapter)
                    task = queue.sync { session.uploadTask(with: urlRequest, from: data) }
                case let .file(url, urlRequest):
                    let urlRequest = try urlRequest.adapt(using: adapter)
                    task = queue.sync { session.uploadTask(with: urlRequest, fromFile: url) }
                case let .stream(_, urlRequest):
                    let urlRequest = try urlRequest.adapt(using: adapter)
                    task = queue.sync { session.uploadTask(withStreamedRequest: urlRequest) }
                }

                return task
            } catch {
                throw AdaptError(error: error)
            }
        }
    }

虽然内容与上边的DownloadRequest不同,但是套路却相同。从代码中,也能看出,上传数据有3种介质,分别是:data,file,stream。

StreamRequest:

enum Streamable: TaskConvertible {
        case stream(hostName: String, port: Int)
        case netService(NetService)

        func task(session: URLSession, adapter: RequestAdapter?, queue: DispatchQueue) throws -> URLSessionTask {
            let task: URLSessionTask

            switch self {
            case let .stream(hostName, port):
                task = queue.sync { session.streamTask(withHostName: hostName, port: port) }
            case let .netService(netService):
                task = queue.sync { session.streamTask(with: netService) }
            }

            return task
        }
    }

netService超出了本文的范围,就不做介绍了,平时用的也少。

我们对上边这些struct,enum做一个总结:由于struct,enum是值拷贝,因此他们比较适合作为数据的载体。一个方案的逻辑中,如果可能出现多个可能性,就考虑使用enum。还有最重要的一点,尽量把一个单一的功能的作用域限制的越小越好。功能越单一,结构越简单的函数越安全。

忽略的内容

在Request.swift的源码中,还有一个给任务添加进度的方法,在这里就不做介绍了,原理就是自定义一个函数,传递给task的代理。在DownloadRequest中对取消下载任务做了一些额外的处理。还有设置下载后的目录等等。

DownloadOptions

这个DownloadOptions其实挺有意思的,他实现了OptionSet协议,因此它就有了集合的一些特性。

在OC中,我们往往通过掩码来实现多个选项共存这一功能,但DownloadOptions用另一种方式实现了这一功能:

/// A collection of options to be executed prior to moving a downloaded file from the temporary URL to the
    /// destination URL.
    public struct DownloadOptions: OptionSet {
        /// Returns the raw bitmask value of the option and satisfies the `RawRepresentable` protocol.
        public let rawValue: UInt

        /// A `DownloadOptions` flag that creates intermediate directories for the destination URL if specified.
        public static let createIntermediateDirectories = DownloadOptions(rawValue: 1 << 0)

        /// A `DownloadOptions` flag that removes a previous file from the destination URL if specified.
        public static let removePreviousFile = DownloadOptions(rawValue: 1 << 1)

        /// Creates a `DownloadFileDestinationOptions` instance with the specified raw value.
        ///
        /// - parameter rawValue: The raw bitmask value for the option.
        ///
        /// - returns: A new log level instance.
        public init(rawValue: UInt) {
            self.rawValue = rawValue
        }
    }

上边的代码只扩展了两个默认选项:

  • createIntermediateDirectories
  • removePreviousFile

可以采用类似的手法,自己扩展更多的选项。看一下下边的例子就明白了:

var op = DownloadRequest.DownloadOptions(rawValue: 1)
        op.insert(DownloadRequest.DownloadOptions(rawValue: 2))
        if op.contains(.createIntermediateDirectories) {
            print("createIntermediateDirectories")
        }
        if op.contains(.removePreviousFile) {
            print("removePreviousFile")
        }

上边代码中,if语句内的打印都会调用。

总结

这一篇文章与上一篇间隔了很长时间,原因是公司做了一个项目。这个中小型项目结束后,也有一些需要总结的地方,我会把这些感触写下来,和大家讨论一些项目开发的内容。

读的越多,越发觉得Alamofire中的函数的设计很厉害。不是一时半会能够全部串联的。

由于知识水平有限,如有错误,还望指出

链接

Alamofire源码解读系列(一)之概述和使用 简书-----博客园

Alamofire源码解读系列(二)之错误处理(AFError) 简书-----博客园

Alamofire源码解读系列(三)之通知处理(Notification) 简书-----博客园

Alamofire源码解读系列(四)之参数编码(ParameterEncoding) 简书-----博客园

Alamofire源码解读系列(五)之结果封装(Result) 简书-----博客园

Alamofire源码解读系列(六)之Task代理(TaskDelegate) 简书-----博客园

Alamofire源码解读系列(七)之网络监控(NetworkReachabilityManager) 简书-----博客园

Alamofire源码解读系列(八)之安全策略(ServerTrustPolicy) 简书-----博客园

Alamofire源码解读系列(九)之响应封装(Response) 简书-----博客园

Alamofire源码解读系列(十)之序列化(ResponseSerialization) 简书-----博客园

Alamofire源码解读系列(十一)之多表单(MultipartFormData) 简书-----博客园

Alamofire源码解读系列(十二)之时间轴(Timeline) 简书-----博客园

posted @ 2017-05-15 15:32  马在路上  阅读(3143)  评论(0编辑  收藏