Alamofire 5.0 迁移指南

即将离开简书,请到掘金继续关注我。谢谢!

本文掘金链接

为什么离开

此文章是对 Alamofire 5.0 Migration Guide 的翻译,有需要的可以去看原文。

另外此文章的内容也保存到了我的 GitHub 仓库,建议去 GitHub 阅读,以获得更好的阅读体验。如果觉得对你有用的,可以顺手给个 Star。谢谢!

Alamofire 5.0 迁移指南

Alamofire 5.0 是 Alamofire 的最新主要版本,它是一个使用 Swift 编写的用于 iOS、tvOS、macOS 和 watchOS 的 HTTP 网络库。作为一个主要版本,遵循语义版本控制约定,5.0 引入了影响 API 的更改。

提供该指南是为了简化现有的使用了 Alamofire 4.x 的应用程序更新到最新 API 的转换,以及解释新的和更新的功能的设计和结构。由于 Alamofire 5 中更改的广泛性,本指南没有提供所有更改的完整概述。想要了解更多,用户可以去阅读 Alamofire 的 API 和使用文档。

升级的好处

  • 重写核心:Alamofire 的核心架构已经被重写,以遵循各种最佳实践。
    • DispatchQueue 的使用已更新,以遵循苹果推荐的最佳实践。这意味着,当许多请求同时运行时,Alamofire 的表现将大大提高,而不能像以前的版本那样导致队列耗尽。这将提高整体性能,降低 Alamofire 对应用程序和系统的影响。
    • 内部 APIs 已经明确了责任领域,使得实现某些特性变得更加容易,比如新的 EventMonitor 协议和每个请求的 SSL 失败错误等等。
    • 它从一开始就使用了各种净化,特别是线程净化,因此线程和其他运行时问题将比以前的版本少得多。
  • Decodable ResponsesResponseDecodableDecodableResponseSerializer 现在提供了内置支持,可以使用任何 DataDecoder 类型从网络响应中解析 Decodable 类型。
  • Encodable Parameters:Alamofire 现在支持并倾向于使用 ParameterEncoder 协议将 Encodable 类型作为参数,允许对请求参数进行完全类型安全的展示。
  • URLEncodedFormEncoder:除了支持常见的 Encodable 参数外,Alamofire 现在还包括 URLEncodedFormEncoder,一种用于 URL 表单编码的 Encoder
  • EventMonitor 协议EventMonitor 允许访问 Alamofire 的内部事件,这使得在请求的生命周期中观察特定的操作更加容易。这使得日志记录请求非常容易。
  • 异步的 RequestAdapterRequestAdatper 协议现在可以异步操作,从而可以向请求添加异步资源。
  • 单个 Request RequestInterceptor:现在可以将 RequestInterceptor 添加到单个请求中,从而首次实现细粒度控制。
  • CachedResponseHandlerRedirectHandler 协议:在会话和请求的基础上,轻松访问和控制响应缓存和重定向行为。
  • HTTPHeaders 类型:类型安全访问常见的 HTTP 头文件,扩展了URLRequestHTTPURLResponseURLSessionConfiguration,允许使用 Alamofire 的新类型设置这些类型的头文件。
  • RetryPolicy:一种自动支持重试由于网络或其他系统错误而失败的请求的 RequestRetrier,具有可自定义的回退、重试限制和其他参数。

API 变化

Alamofire 5 中的大多数 API 都已更改,因此此列表并不完整。虽然大多数顶层的请求 APIs 保持不变,但几乎所有其他类型都以某种方式发生了变化。有关最新示例,请参阅使用文档。

  • SessionManager 已重命名为 Session,并且它的 APIs 也已完全改变。
  • SessionDelegate 已重新编写,其公共 API 已完全更改。各种闭包重写已经被删除,大多数现在可以用特定的 Alamofire 特性替换。如果需要控制以前用闭包来实现的功能,可以随时打开一个特性请求。
  • TaskDelegate 和 各种 *TaskDelegate 已经被删除。所有 URLSession*Delegate 处理现在都由 SessionDelegate 执行。
  • Result 已被删除。 Alamofire 现在使用 Swift 的 Result 类型。
  • 全局 Alamofire 名称空间(这从来都不是必需的)已经被删除,并替换为 AF,并且实际上是对 Session.default 的引用。
  • ServerTrustPolicyManager 已重命名为 ServerTrustManager,现在需要每个已评估的请求与提供的主机之一匹配。这可以在初始化实例时通过设置 allHostsMustBeEvaluted: false 来禁用。
  • ServerTrustPolicy 被改为 ServerTrustEvaluating 协议和几个遵循这个协议的类型。现在,每个 ServerTrustPolicy 案例都有对应的类型:
    • .performDefaultEvaluationDefaultTrustEvaluator 代替.
    • .performRevokedEvaluationRevocationTrustEvaluator 代替.
    • .pinCertificatesPinnedCertificatesTrustEvaluator 代替.
    • .pinPublicKeysPublicKeysTrustEvaluator 代替.
    • .disableEvalutionDisabledTrustEvalutor 代替.
    • .customEvaluationCompositeTrustEvalutor (用于组合已存在的 ServerTrustEvaluating 类型) 或者自定义遵循 ServerTrustEvaluating 协议的类型代替.
  • DataResponseDownloadResponse 现在对响应类型和错误类型都是双重通用的。默认情况下,所有 Alamofire APIs 都返回一个 AF 前缀的响应类型,并且将 Error 类型默认为 AFError。
  • Alamofire 现在为其所有 APIs 返回 AFError,在 AFError 实例中包装任何底层系统或自定义 APIs。
  • HTTPMethod 现在是一个结构而不是一个枚举,可以扩展以提供自定义方法。
  • AFError 现在有几个新的案例,因此对它进行 switch 操作必须处理这几个新增的案例。
  • Alamofire 提供的 Notifications 已将其 keys 重命名。您现在可以订阅:
    • 当请求及其 URLSessionTasks 调用 resume() 时,将发出 Request.didResumeNotificationRequest.didResumeTaskNotification 通知。
    • 当请求及其 URLSessionTasks 调用 suspend() 时,将发出 Request.didSuspendNotificationRequest.didSuspendTaskNotification 通知。
    • 当请求及其 URLSessionTasks 调用 cancel() 时,将发出 Request.didCancelNotificationRequest.didCancelTaskNotification 通知。
    • 当请求及其 URLSessionTasks 调用 finish()URLSessionTask 触发 didComplete 代理方法时,将发出 Request.didFinishNotificationRequest.didCompleteTaskNotification 通知。
  • MulitpartFormData 的 API 已经更改,用于创建和上传 MultipartFormData 的顶层 upload 方法已经更新,以匹配其他请求 APIs,因此不再需要处理 multipart 编码的 Result
  • NetworkReachabilityManager 已经过重构,以获得更高的可靠性和简单性。不再是设置一个更新闭包,然后启动监听器,这个闭包已经提供给了 startListening 方法。
  • Request 及其各种子类已被重写,并且公共 API 已完全更改。有关当前功能的详细列表,请参阅文档。
  • Timeline 和 Alamofire 以前的 URLSessionTaskMetrics 处理已经被替换为系统自带的 URLSessionTaskMetrics,后者现在为 Alamofire 的请求提供所有计时信息。
  • Request 的 cURL 表示已从 debugDescription 中删除,该方法现在对调试输出很有用,并被放在了 cURLDescription 方法,该方法提供对 cURL 命令的基于完成处理程序的访问。
  • DefaultDataResponseDefaultDownloadResponse 已被删除。所有 response 方法现在都返回 DataResponseDownloadResponse 类型。
  • DataResponseSerializerProtocolDownloadResponseSerializer 协议的要求已从属性 serializeResponse 更改为函数 serializeResponse 。此函数可以返回序列化值或引发错误,不再需要 Result 返回值。新的 ResponseSerializer 协议组合了前两个协议来简化实现。
  • RequestAdapter 已更新为具有异步需求,允许在请求调整期间访问异步资源。

新特性

  • Alamofire 现在通过 af 名称空间提供 Swift 和 Foundation 类型的扩展。
  • 序列化器更新了更多的配置选项,包括允许空响应方法和代码,以及 DataPreprocessor 协议,以便为序列化接收的 Data 做准备。
  • RetryPolicyRequestRetrier,用于重试由于系统错误(如网络连接)而失败的请求。可配置自定义的解除缓冲设置,并默认为一系列错误,以使您的请求更可靠。
  • CachedResponseHandler:新的协议,它提供了对响应是否被缓存的控制。 ResponseCacher 类型是作为协议的易于使用的实现而提供的。
  • RedirectHandler:提供对请求重定向行为控制的新协议。 Redirector 类型是作为协议的易于使用的实现提供的。
  • ParameterEncoder:新的协议,它支持将 Encodable 的值编码到 URLRequestJSONParameterEncoderURLEncodedFormParameterEncoder 包含在 Alamofire 中。
  • URLEncodedFormEncoder:生成 URLEncodedForm 字符串的 Encoder

推荐阅读更多精彩内容