Skip to content

Tiercel 3.0 迁移指南

Jump to bottom
Daniels edited this page Jan 15, 2020 · 1 revision

Tiercel 3.0 进行了大量的代码重构，大幅提高了性能，拥有更完善的错误处理，提供了更多方便的 API。尽管如此，总体的使用方法并没有发生重大的改变，开发者可以很容易进行升级。

如果之前有使用过 2.3.0 或者更新的版本，可以直接更新到 3.0.0 版本，再进行少量的改动即可完成升级；否则需要先升级到 2.4.1 作为过渡，原因会在后面具体说明。

环境要求

  • iOS 10.0+
  • Xcode 11.0+
  • Swift 5.0+

从 3.0.0 版本开始，Tiercel 改为最低支持 iOS 10.0，目前很多主流的 Swift 开源库都是如此，iOS 10.0 以下的使用者应该是非常少了，从 Xcode 11.0 开始也默认不支持 iOS 10.0 以下的模拟器，抛弃老旧的系统版本，可以更方便的使用新的 API，os_unfair_lock就是其中一个。

而 Swift 则是一门非常年轻的语言，一直在快速发展，其实从 Swift 3 开始它的 API 改动已经不大，到了 Swift 5 ABI 稳定下来，所以 Tiercel 直接使用最新的 Swift 版本，方便使用最新的特性。

Tiercel 3.0 全面进化

改进

  • 大幅提高multiDownload(_:headersArray:fileNames:)、totalSuspend(onMainQueue:handler:)、totalCancel(onMainQueue:handler:)、totalRemove(completely:onMainQueue:handler:)等批量操作的速度
  • 改用字典来匹配任务，提高fetchTask(_:)方法的性能
  • 改用 iOS 中性能最高的锁os_unfair_lock进行线程同步
  • 更完善的错误处理，任何错误都会打印出来
  • 将TiercelLog改成struct Logger: Logable，开发者可以取消所有的默认打印，也可以自定义Logger
  • 修改部分属性名称和方法名称，更加规范
  • 提高线程安全

新增

  • Cache支持自定义下载模块的文件夹
  • 支持 iOS 13 的低数据模式访问限制和昂贵网络访问限制
  • 支持改变单个任务在所有任务中的位置
  • 支持对所有任务进行排序
  • 增加直接对任务进行操作的API，如：sessionManager.cancel(task)

迁移

Tiercel 3.0 内部代码改动很大，性能得到很大的提高，但是提供给外界使用的 API 却改动很小，所以只需从以下几个方面进行少量修改

NSCoding

在 2.3.0 版本以前，Tiercel 使用NSCoding做编码解码，实现下载任务的持久化。从 2.3.0 版本开始，Tiercel 改用Codable，更加安全。后续的版本 Tiercel 做了兼容处理，会先使用NSCoding解码，然后就使用Codable编码解码。考虑到这种情况已经持续很久，所以从 3.0.0 版本开始，移除对NSCoding的兼容。如果之前有使用过 2.3.0 或者更新的版本，可以直接更新到 3.0.0 版本；否则需要先升级到 2.4.1 作为过渡。

带闭包参数的方法

在 Tiercel 2.0 中，SessionManager提供了一些对DownloadTask操作，如暂停、取消、删除、验证文件，这些方法最后一个参数都是闭包，作为操作完成后的回调，如下

public func cancel(_ url: URLConvertible, onMainQueue: Bool = true, _ handler: Handler<DownloadTask>? = nil)

最后一个闭包是可选类型，并且默认为nil，同时省略了外部参数名称，为了使这些方法变得更加规范，在 Tiercel 3.0 中不再省略这个闭包参数的外部参数名称，如下：

public func cancel(_ url: URLConvertible, onMainQueue: Bool = true, handler: Handler<DownloadTask>? = nil)

这样最后一个参数就是尾随闭包，调用的时候可以写成这样：

sessionManager?.cancel(URLString) { task in
    // 具体操作
}

当然，如果你在 Tiercel 2.0 已经是这样写，那么将无需任何改动

移除TiercelLog

旧版本提供了一个全局方法TiercelLog(_:identifier:url:file:line:)，可以方便的打印调试日志。但为了代码更加简洁，日志模块化，新版本移除了这个方法。

作为替代，Tiercel 3.0 SessionManager的初始化方法中增加了一个Logable类型参数

public init(_ identifier: String,
                configuration: SessionConfiguration,
                logger: Logable? = nil,
                cache: Cache? = nil,
                operationQueue: DispatchQueue = DispatchQueue(label: "com.Tiercel.SessionManager.operationQueue")) { 
    // ....
}

开发者可以遵守Logable协议，自定义一个logger

public enum LogOption {
    case `default`
    case none
}

public enum LogType {
    case sessionManager(_ message: String, manager: SessionManager)
    case downloadTask(_ message: String, task: DownloadTask)
    case error(_ message: String, error: Error)
}

public protocol Logable {
    var identifier: String { get }
    
    var option: LogOption { get set }
    
    func log(_ type: LogType)
}

SessionManager

如上面所示，static var logLevel: LogLevel已经改成LogOption类型集成到Logable中

而同样为了模块化，static var isControlNetworkActivityIndicator: Bool也改为SessionManager的实例属性。

为了避免歧义，var completedTasks: [DownloadTask]改成var succeededTasks: [DownloadTask]

下载信息

Tiercel 3.0 为了让外界更方便地使用下载信息，分别在SessionManager和DownloadTask中增加了各种下载信息的String类型版本计算属性，原来的属性也保留下来，因此也无需进行改动，开发者可以用原来的属性生成其他格式的String

其他改动

以上应该包含了所有迁移到 Tiercel 3.0 需要进行的修改，如果还有的话，应该也可以借助编译器的警告提示来进行修改。当然，实在还有问题，你也可以向我发问

Clone this wiki locally