Alamofire 的设计之道

阅读 4486
收藏 61
2017-06-19
原文链接:www.jianshu.com

前言:

Alamofire是一个由Swift编写的优雅的网络开发框架。

大部分用Swift编写的iOS App的网络模块都是基于Alamofire的。作为Swift社区最活跃的几个项目之一,有许多开发者在不断的对其进行完善,所以学习这种优秀的开源代码对深入理解Swift的特性很有帮助。

本文很长,大到整个框架的设计,小到某些基础功能的使用都会涉及。


URL Loading System

iOS的网络开发(URL Loading System)的类层次如下:


从图中可以看出,整个框架包括URL Loading相关的核心类和五种辅助类。其中,五种辅助类划分如下

  • Configuration 配置信息,比如Cookie的存储策略,TLS版本等等。
  • Authentication and Credentials 授权和证书
  • Protocol support 用做proxy来拦截或特殊处理某些URL
  • Cookie Storage 管理Cookie
  • Cache Management 管理缓存

Alamofire就是建立在NSURLSession上的封装。

NSURLSession是在2013年推出的新API,并且Apple在2015年废弃了NSURLConnection。如果你的App还在用以NSURLConnection建立的网络层(比如AFNetworking 2.x),那么你真的应该考虑升级到NSURLSession(比如AFNetworking 3.x),废弃的API也许还能正常工作,但是Apple已对其不再维护,当然也就不支持HTTP 2.0等新特性。

关于NSURLSesson的基础使用,我之前有过几篇博客,可以在这个链接找到:

那么,用NSURLSession来进行HTTP/HTTPS请求的时候,实际的过程如何呢?


  • 建立NSURLSessionTask,并且resume.
  • 检查cache策略,如果有需要从本地cache中直接返回数据
  • 通过DNS进行域名查找
  • 建立TCP连接
  • 如果是HTTPS,进行TLS握手(如有资源需要认证访问,可能需要客户端提供证书,用户名密码等信息)
  • 请求开始,收到HTTP的Response
  • 接收HTTP的Data

Tips: 理解HTTP/HTTPS的请求过程很重要,因为往往你需要统计API请求在哪个阶段出了问题,然后对症下药,提高用户体验。


整体架构

Alamofie的整体功能图如下:


其中

  • 左侧是暴露给外部的接口,右侧是内部实现相关
  • 这三个模块比较独立:AlamofireImageAlamofireNetworkActivityIndicator 是基于Alamofire开发的独立的库,分别用来做图片和网络状态小菊花,NetworkReachabilityManager也是先对独立的用来检测蜂窝移动,WIFI等网络变化的。

我们先从一个API调用切入,来分析各个模块的作用:

Alamofire.request(/**/).validate(/**/).responseJSON {/**/}

初始化SessionManager的单例default

//整理后代码
self.delegate = SessionDelegate()
self.session = URLSession(configuration: configuration, delegate: delegate, delegateQueue: nil)

在初始化SessionManager代码里,提供了一个默认的SessionDelegate,并且初始化了一个URLSession,这个URLSession的delegate是SessionDelegate。

通过这个初始化,我们知道URLSession的几个代理事件都是传递给SessionManager的SessionDelegate了。

执行全局方法Alamofire.request

方法体中调用SessionManager.default单例的实例方法来创建DataRequest。这一步做了如下动作:

  • 根据传入的url,parameters等参数创建URLRequest
  • 根据URLRequestSessionManager的属性session(URLSession),adapter(请求适配器),queue(GCD queue)创建URLSessionDataTask
  • 根据基类Request提供的方法,创建子类DataRequest实例,并且为子类DataRequest初始化一个DataTaskDelegate

每一个DataRequest对应一个DataTaskDelegate,每一个TaskDelegate有一个OperationQueue,这个queue在初始化的时候是挂起状态的,并且是一个串行队列(maxConcurrentOperationCount = 1)。

open class 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
        //省略
    }
    delegate.error = error
    delegate.queue.addOperation { self.endTime = CFAbsoluteTimeGetCurrent() } //加入统计请求结束的Operation
    }
}
  • 按需执行DataTask的resume方法

执行DataTask.validate

内容很简单,就是把传入的闭包保存起来,等待后续执行,并且返回Self

执行DataTask.responseJSON

在这个方法里,创建一个NSOperation加入到DataTaskDelegate的queue中,这个queue在创建之初是刮挂起状态的,所以提交的任务不会执行

URLSession收到数据

首先SessionDelegate代理方法被调用:

open func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
    if let dataTaskDidReceiveData = dataTaskDidReceiveData {//有自定义实现
            dataTaskDidReceiveData(session, dataTask, data)
        } else if let delegate = self[dataTask]?.delegate as? DataTaskDelegate {//走默认实现
            delegate.urlSession(session, dataTask: dataTask, didReceive: data)
        }
}

在这个代理方法里,根据存储的字典 URLSessionTask -> TaskDelegate 找到这个task的DataTaskDelegate,调用其方法

 func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
    //整理后代码
    mutableData.append(data) //存储数据到内存
   progressHandler.queue.async { progressHandler.closure(self.progress) } //回调progressHandler
}

URLSession完成Task

首先调用SessionDelegate中的URLSession的代理方法

open func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
//整理后代码

//执行response的validation
request.validations.forEach { $0() } 
//唤起queue,来执行提交的任务
strongSelf[task]?.delegate.queue.isSuspended = false
strongSelf[task] = nil
}

由于queue被唤起,所以之前提交的完成callback会被执行。

执行网络请求完成的callback

//序列化请求结果,这里的responseSerializer为DataResponseSerializerProtocol协议类型
let result = responseSerializer.serializeResponse(
                self.request,
                self.response,
                self.delegate.data,
                self.delegate.error
            )
//建立Response对象
var dataResponse = DataResponse<T.SerializedObject>(
    request: self.request,
    response: self.response,
    data: self.delegate.data,
    result: result,
    timeline: self.timeline
)
//增加统计相关信息
dataResponse.add(self.delegate.metrics)

//执行传入的必报,也就是responseJSON函数传入的闭包
(queue ?? DispatchQueue.main).async { completionHandler(dataResponse) }

API设计

衡量一个框架好坏最重要的因素就是是否容易使用。

那么,如何定义容易使用呢?

根据二八原则,对于一个框架的使用百分之八十的时候都是很基础的功能使用,当这些基础的功能使用是容易的,我们认为这个框架是容易使用的。

我们来对比一下,同样GET一个URL,然后把数据解析成JSON。使用NSURLSession层次的API如下

guard let url = URL(string: "https://raw.githubusercontent.com/LeoMobileDeveloper/React-Native-Files/master/person.json") else {
    return;
}
let dataTask = URLSession.shared.dataTask(with: url) { (data, response, error) in
    guard let data = data else{
        return;
    }
    do{
        let json = try JSONSerialization.jsonObject(with: data, options: .allowFragments)
        print(json)
    }catch let error{
        print(error)
    }
};
dataTask.resume()

使用Alamofire

Alamofire.request("https://raw.githubusercontent.com/LeoMobileDeveloper/React-Native-Files/master/person.json").responseJSON { (response) in
    if let JSON = response.result.value {
        print("JSON: \(JSON)")
    }
}

Tips: 这里的Alamofire.request指的是module(模块) Alamofire的一个全局方法request调用。

可以看到,使用系统的API,我们不得不先创建URL,然后建立DataTask,并且Resume。接着在callback里去解析JSON。由于Swift是一种强类型的语言,我们不得不进行大量的逻辑判断和try-catch。

而Alamofire把这些步骤简化成了一个静态的方法调用,并且用链式的方式来处理异步的Response解析。由于是链式的,你可以用链式的方式实现很多逻辑,比如验证返回值:

Alamofire.request("https://httpbin.org/get")
    .validate(statusCode: 200..<300) //返回值验证
    .responseData { response in //解析返回的数据
        switch response.result {
        case .success:
            print("Validation Successful")
        case .failure(let error):
            print(error)
        }
    }

用链式的方式进行异步处理是一个很好的实践,延伸阅读可以参考:PromiseKitRxSwift

链式的异步处理有很多优点:

  • 优雅的处理大量的callback
  • 代码更容易理解,更容易维护
  • 不需要在每一步都进行错误检查

80%情况下的API调用

Alamofire是采用静态方法的方式来提供80%情况下的API,这些全局方法可以在Alamofire.swift找到,以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
    )
}

我们来分析下这个简单却又精炼的方法,方法的几个参数

  • url 请求的URL,协议URLConvertible类型(Alamofire用extension的方式为URL,String,URLComponents实现了这个协议)
  • method 请求的HTTP方法,默认为GET
  • parameters 请求的参数,默认为nil
  • encoding,,参数编码类型,默认URLEncoding.default,也就是根据HTTP方法的类型决定参数是query或者body里
  • headers, HTTP Header

返回值是一个DataRequest实例,这个实例就是异步调用链的头部。

Tips: 用默认参数来实现默认配置是一个很好的实践。

如何实现链式调用

open class Request {
    var validations: [() -> Void] = []
    public func validate(_ validation: @escaping Validation) -> Self {
        let validationExecution: () -> Void = {/**/}
        validations.append(validationExecution)
        return self
    }
}

从代码中,我们可以比较清楚的看出链式调用的原理:

函数的参数是闭包类型,方法体把这个闭包类型输入存储起来,并且返回Self。在合适的时候执行闭包即可实现异步的链式调用。


模块功能

软件设计有一个非常重要的原则就是:单一功能原则。

Alaofire的文件划分如下:


我们来分析Alamofire的各个模块负责的功能:

  • SessionManager 整个Alamofire框架的核心枢纽,封装了URLSession。负责提供外部调用的API,处理请求适配器,请求的重拾。
  • SessionDelegate SessionManager的代理,封装了URLSessionDelegate。负责对Task的回调事件提供默认实现(转发给TaskDelegate进行实际处理),并且以闭包的方式暴露给外部,让外部可以自定义实现。
  • TaskDelegate 对URLSessionTask的回调进行实际的处理,并且执行task的完成回调用
  • Request 是URLSessionTask的封装,是暴露给上层的请求任务
    • ParameterEncoding 对参数进行Encoding(JSON,query等)
  • Response 代表返回数据序列化后的结果
    • ResponseSerializer 对返回的数据进行序列化(JSON,property list等)
  • ServerTrustPolicyManager/ServerTrustPolicy 对TLS等过程中发生的认证进行处理
  • Timeline 纯粹的用来进行网络请求过程的数据统计

线程

Alamofire的线程处理都是采用GCD和NSOperation,并没有使用底层的Thread。

SessionManager

每一个SessionManager有一个常量属性

let queue = DispatchQueue(label: "org.alamofire.session-manager." + UUID().uuidString)

这个queue用来做task的初始化工作,也做了比如文件创建等

//task初始化
return task = queue.sync { session.downloadTask(with: urlRequest) }
//创建目录
try fileManager.createDirectory(at: directoryURL, withIntermediateDirectories: true, attributes: nil)

URLSession

Session是这样被初始化的:

self.session = URLSession(configuration: configuration, delegate: delegate, delegateQueue: nil)

delegateQueue是URLSession的各种回调函数被调用的串行队列,这里传入nil,表示由系统自动为我们创建回调队列。

GlobalQueue

关于全局队列,有如下使用

//重试
DispatchQueue.utility.after{}

//初始化上传的MultipartFormData
DispatchQueue.global(qos: .utility).async

TaskDelegate

每一个Task有一个TaskDelegate,每一个TaskDelegate有一个常量属性queue

self.queue = {
            let operationQueue = OperationQueue()

            operationQueue.maxConcurrentOperationCount = 1
            operationQueue.isSuspended = true
            operationQueue.qualityOfService = .utility

            return operationQueue
        }()

这个queue有一点黑科技,在创建的时候是挂起的,然后不断的往里塞任务:比如responseJSON等。然后等Task完成的时候,再唤起queue,执行这些任务。

还是举一个例子,我们来看看队列之前的切换:

Alamofire.request(/**/).validate(/**/).responseJSON {/**/}
  • 主队列调用request方法
  • syncSessionManager的queue上创建URLSessionDataTask
  • 主队列调用validate方法和responseJSON保存相关闭包
  • URLSession中由系统自动创建的queue收到delegate事件回调
  • 收到URLSessionTask完成的回调,TaskDelegate的queue被唤起
  • 异步到主队列执行responseJSON中传入的闭包

当然,上述的队列使用不包括以参数方式传递进入的,比如responseJSON,就可以指定这个闭包执行的队列

  public func responseJSON(
        queue: DispatchQueue? = nil,
        options: JSONSerialization.ReadingOptions = .allowFragments,
        completionHandler: @escaping (DataResponse<Any>) -> Void)
        -> Self{}

错误处理

数据结构

AlamoFire的错误处理是采用了带关联值枚举,在Swift开发中,枚举是最常见的用来处理错误的。

在关联值枚举中,Alamofire还定义了内部类型,来对错误类型进行二次分类。代码如下:

public enum AFError: Error {
    public enum ParameterEncodingFailureReason {/*省略*/}
    public enum MultipartEncodingFailureReason {/*省略*/}
    public enum ResponseValidationFailureReason {/*省略*/}
    public enum ResponseSerializationFailureReason {/*省略*/}

    //枚举的可能值
    case invalidURL(url: URLConvertible)
    case parameterEncodingFailed(reason: ParameterEncodingFailureReason)
    case multipartEncodingFailed(reason: MultipartEncodingFailureReason)
    case responseValidationFailed(reason: ResponseValidationFailureReason)
    case responseSerializationFailed(reason: ResponseSerializationFailureReason)
}

我们来分析为什么要这样定义这些错误类型,一个典型的网络库的请求数据流如下:

其中,在调用URLSession相关的API之前,我们要先创建URLRequest,然后交给URLSession去做实际的HTTP请求,然后拿到HTTP请求的二进制数据,根据需要转换成字符串/JSON等交给上层。

所以,Alomofire的错误处理思想是:

根据错误发生的位置进行一级分类,再用嵌套类型对错误进行二次分类。

除了错误定义之外,开发者抓到错误能有友善的描述信息也是很重要的,这就是。Swift提供LocalizedError

extension AFError: LocalizedError {
    public var errorDescription: String? {
          /*省略*/
    }
}
extension AFError.ParameterEncodingFailureReason {
    var localizedDescription: String {
      /*省略*/
    }
}

Swift错误处理延伸阅读: 详解Swift中的错误处理


继承

NRULSessionTask是由继承来实现的,继承关系如下

  • URLSessionTask — Task的基类
    • URLSessionDataTask - 拉取URL的内容NSData
      • URLSessionUploadTask — 上传数据到URL,并且返回是NSData
    • URLSessionDownloadTask - 下载URL的内容到文件
    • URLSessionStreamTask — 建立TCP/IP连接

仿照这种关系,Alamofire的Request也是类似的继承关系:

  • Request — Task的基类
    • DataRequest - 拉取URL的内容NSData
      • UploadRequest — 上传数据到URL,并且返回是NSData
    • DownloadRequest - 下载URL的内容到文件
    • StreamRequest — 建立TCP/IP连接

其实原因和很简单:父类提供基础的属性和方法来给子类复用。

在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
            /**/
        }
    }

协议

Swift是面向协议编程的语言。

Alamofire的很多设计都是以协议为中心的,


以ParameterEncoding协议:

定义如下:

public protocol ParameterEncoding {
    func encode(_ urlRequest: URLRequestConvertible, with parameters: Parameters?) throws -> URLRequest
}

接口依赖于这个协议类型

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

这样在传入的时候,只要是这个协议类型都可以,不管是struct,enum或者class。

Alamofire实现了三种Encoding方式:

public struct URLEncoding: ParameterEncoding {}
public struct JSONEncoding: ParameterEncoding {}
public struct PropertyListEncoding: ParameterEncoding {}

扩展性

由于提供的接口是协议类型的,于是你可以方便直接把一个实例当作url,并且自定义encodeing方法

enum API:URLConvertible{
    case login
    public func asURL() throws -> URL {
        //Return login URL
    }
}
class CustomEncoding: ParameterEncoding{/*/*}

然后,你就可以这么调用了

Alamofire.request(API.login, method: .post, encoding: CusomEncoding())

可以看到,使用协议提供的接口是抽象的接口,与具体的class/enum/struct无关,也就易于扩展


代理

代理是CocoaTouch一个很优秀的设计模式,它提供了一种盲通信的方式把相关的任务划分到不同的类中。

在Alamofire中,最主要的就是这两对代理关系:


由于Delegate的存在,

  • SessionManager只需要关注URLSession的封装即可,session层面的事件回调交给由SessionDelegate处理
  • Request只需要关注URLSessionTask的封装,task层面的任务交给RequestDelegate处理。

这样,保证了各个模块之间的功能单一,不会互相耦合。


类型安全

Swift本身是一种类型安全的语言,这意味着如果编译器发现类型不对,你的代码将编译不通过。

URLRequest有一个属性是HTTPMethod

var httpMethod: String? { get set }

它的类型是String类型,这意味着你可以随意的赋值,编译器缺不会提示你你的输入可能又问题。

request.httpMethod = "1234"

考虑到HTTPMethod无非也就是那几种,很适合用enum来做,Alamofire对其进行了封装

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"
}

然后,上层的方法提供的接口是枚举类型:

public func request(
    _ url: URLConvertible,
    method: HTTPMethod = .get, //这里
    parameters: Parameters? = nil,
    encoding: ParameterEncoding = URLEncoding.default,
    headers: HTTPHeaders? = nil)
    -> DataRequest
{
    /*略*/
}

这样,编译器就能够进行合理的检查,也不容易出错了。


版本与平台适配

Alamofire适配的平台有ios/osx/tvos/watchos,适配的最低iOS版本是iOS 8。 那么,就出现了一个问题

  • 有些平台没有对应的API
  • 有些API是高版本的系统才有的

举个例子:

func streamTask(with service: NetService) -> URLSessionStreamTask

Alamofire采用如下方式进行适配:

@avialable - 用来标记适配系统版本(for编译器)

比如,这个函数被标记为iOS 9.0后可用,如果直接在target iOS 8的调用,则会报错。可以在if #available{}中调用

@discardableResult
@available(iOS 9.0, macOS 10.11, tvOS 9.0, *)
public func stream(withHostName hostName: String, port: Int) -> StreamRequest {
    return SessionManager.default.stream(withHostName: hostName, port: port)
}

#if ... #endif - 用作条件编译(for编译器)

例如:在watchOS上不编译

#if !os(watchOS)
@discardableResult
@available(iOS 9.0, macOS 10.11, tvOS 9.0, *)
public func stream(withHostName hostName: String, port: Int) -> StreamRequest {
    return SessionManager.default.stream(withHostName: hostName, port: port)
}
#endif

#available - 满足平台和系统要求才调用(for 编译器,运行时)

extension Response {
    mutating func add(_ metrics: AnyObject?) {
        #if !os(watchOS)
            guard #available(iOS 10.0, macOS 10.12, tvOS 10.0, *) else { return }
            guard let metrics = metrics as? URLSessionTaskMetrics else { return }

            _metrics = metrics
        #endif
    }
}

总结

Alamofire是一个优雅的Swift开源库,它的代码真的很优雅,强烈建议对Swift感兴趣并且想深入学习的同学用几天的空余时间去研究下。看的时候多问自己几个问题:

  • 为什么这里要用protocol而不用继承?
  • 为什么这里要用struct而不用class?
  • .....

总之,多问为什么,然后找到答案,就会很有收获。

本文同步放到我的github上,如有问题欢迎issue。




快来加入掘金 iOS 开发讨论群

扫描二维码,添加小编好友,回复 ios 拉你进群

评论