Kingfisher源码阅读（一）
Kingfisher是喵神写的一个异步下载和缓存图片的Swift库，github上将近3k的Star，相信不需要我再安利了。它的中文简介在这里，github地址在这里。
我始终觉得编程的精髓是抽象和模块化。阅读别人的代码也应该先从大处着眼，从抽象层面最高的地方开始，自顶向下地逐模块阅读。我花了一个白天加两个晚上认真地读了一遍Kingfisher，加了一些中文注释，本系列比较详细地记录了阅读过程，所以可能会显得有点啰嗦。
Kingfisher的文档非常完备，我先大致看了一下，然后下载源码，跑了一下demo。demo中有这么一段：
cell.cellImageView.kf_setImageWithURL(URL, placeholderImage: nil,
optionsInfo: [.Transition(ImageTransition.Fade(1))],
progressBlock: { receivedSize, totalSize in
print("\(indexPath.row + 1): \(receivedSize)/\(totalSize)")
},
completionHandler: { image, error, cacheType, imageURL in
print("\(indexPath.row + 1): Finished")
}
)
这个kf_setImageWithURL显然是UIImage的一个extension方法，既然是暴露出来供库的使用者调用的，应该就是抽象层面最高的。于是我command+click进去看了一下，它长这个样子：
public func kf_setImageWithURL(URL: NSURL,
placeholderImage: UIImage?,
optionsInfo: KingfisherOptionsInfo?,
progressBlock: DownloadProgressBlock?,
completionHandler: CompletionHandler?) -> RetrieveImageTask
{
return kf_setImageWithResource(Resource(downloadURL: URL),
placeholderImage: placeholderImage,
optionsInfo: optionsInfo,
progressBlock: progressBlock,
completionHandler: completionHandler)
}
主要就是把传过来的URL包装成了一个Resource，然后调用kf_setImageWithResource方法。Resource里面包含了两个属性，cacheKey和downloadURL,cacheKey就是原URL的完整字符串，之后会作为缓存的键使用（内存缓存直接使用cacheKey作为NSCache的键，文件缓存把cacheKey进行MD5加密后的字符串作为缓存文件名）。下面再看看这个kf_setImageWithResource方法，它是这个UIImageView+Kingfisher.swift里的核心方法，其他还有一些提供给用户使用的kf_setImageWithXXX的方法到最后都会调用它。kf_setImageWithResource里有这一句:
let task = KingfisherManager.sharedManager.retrieveImageWithResource(...)
它使用了KingfisherManager这个类，而这个类看名字就知道是整个库的一个管理调度类。KingfisherManager.sharedManager，显然是取KingfisherManaget的一个单例，Swift中的单例模式非常简单，因为有let可以声明imutable的属性，不用担心线程安全问题，只要在 KingfisherManager.swift里像这样写就行：
private let instance = KingfisherManager()
public class KingfisherManager {
public class var sharedManager: KingfisherManager {
return instance
}
...
}
KingfisherManager的单例调用了retrieveImageWithResource，它整合了下载和缓存两大功能，先看一下完整的方法签名：
public func retrieveImageWithResource(resource: Resource,
optionsInfo: KingfisherOptionsInfo?,
progressBlock: DownloadProgressBlock?,
completionHandler: CompletionHandler?) -> RetrieveImageTask
第一个参数类型Resource之前已经说过了，第二个参数类型KingfisherOptionsInfo?是什么呢？它是一个类型别名：public typealias KingfisherOptionsInfo = [KingfisherOptionsInfoItem]，而KingfisherOptionsInfoItem是一个enum：
public enum KingfisherOptionsInfoItem {
case Options(KingfisherOptions)
case TargetCache(ImageCache)
case Downloader(ImageDownloader)
case Transition(ImageTransition)
}
这个枚举的每个枚举项都有关联值，包含了很多信息。KingfisherOptions是一个自定义的Options，就是一个遵守OptionSetType协议的struct，里面有一些选项，可以对下载和缓存时的一些行为进行配置。TargetCache指定一个缓存器(ImageCache的一个实例)，Downloader指定一个下载器（ImageDownloader的一个实例），Transition指定显示图片的动画效果（提供淡入和从上下左右进入这5种效果，也可以传入自定义效果）。
第三个参数类型是DownloadProgressBlock，也是一个别名:
//下载进度(参数:接收尺寸, 总尺寸)
public typealias DownloadProgressBlock = ((receivedSize: Int64, totalSize: Int64) -> ())`
实际上是一个闭包类型，具体会在什么时候调用待会儿会看到。第四个参数类型CompletionHandler也一样是个闭包类型的别名：
public typealias CompletionHandler = ((image: UIImage?, error: NSError?, cacheType: CacheType, imageURL: NSURL?) -> ())
这个看名字就知道会在操作结束之后调用。
返回类型是RetrieveImageTask，它是长这样的：
public class RetrieveImageTask {
// If task is canceled before the download task started (which means the `downloadTask` is nil),
// the download task should not begin.
var cancelled: Bool = false
var diskRetrieveTask: RetrieveImageDiskTask?
var downloadTask: RetrieveImageDownloadTask?
/**
Cancel current task. If this task does not begin or already done, do nothing.
*/
public func cancel() {
// From Xcode 7 beta 6, the `dispatch_block_cancel` will crash at runtime.
// It fixed in Xcode 7.1.
// See https://github.com/onevcat/Kingfisher/issues/99 for more.
if let diskRetrieveTask = diskRetrieveTask {
dispatch_block_cancel(diskRetrieveTask)
}
if let downloadTask = downloadTask {
downloadTask.cancel()
}
cancelled = true
}
}
简单来说它就是一个接收图片的任务，它的内部有三个属性，cancelled是个表明任务是否被取消的flag，diskRetrieveTask和downloadTask分别是“从磁盘获取缓存图片的任务”和“从网络下载图片的任务”，会分别在缓存模块和下载模块中用到，待会儿再细说。至于这个cancel()方法么就是把上面说的两个任务都取消，然后把取消flag设置为true。
看完了retrieveImageWithResource的方法签名，现在来看一下完整的方法，这个方法我认为是整个KingfisherManager的核心：
public func retrieveImageWithResource(resource: Resource,
optionsInfo: KingfisherOptionsInfo?,
progressBlock: DownloadProgressBlock?,
completionHandler: CompletionHandler?) -> RetrieveImageTask
{
//新建任务
let task = RetrieveImageTask()
// There is a bug in Swift compiler which prevents to write `let (options, targetCache) = parseOptionsInfo(optionsInfo)`
// It will cause a compiler error.
//解析optionsInfo
let parsedOptions = parseOptionsInfo(optionsInfo)
let (options, targetCache, downloader) = (parsedOptions.0, parsedOptions.1, parsedOptions.2)
//若强制刷新则联网下载并缓存
if options.forceRefresh {
downloadAndCacheImageWithURL(resource.downloadURL,
forKey: resource.cacheKey,
retrieveImageTask: task,
progressBlock: progressBlock,
completionHandler: completionHandler,
options: options,
targetCache: targetCache,
downloader: downloader)
} else {
//不强制刷新则从缓存中取
let diskTaskCompletionHandler: CompletionHandler = { (image, error, cacheType, imageURL) -> () in
// Break retain cycle created inside diskTask closure below
//完成之后取消任务引用，避免循环引用，释放内存
task.diskRetrieveTask = nil
completionHandler?(image: image, error: error, cacheType: cacheType, imageURL: imageURL)
}
let diskTask = targetCache.retrieveImageForKey(resource.cacheKey, options: options,
completionHandler: { image, cacheType in
if image != nil {
diskTaskCompletionHandler(image: image, error: nil, cacheType:cacheType, imageURL: resource.downloadURL)
} else {
//没有缓存则联网下载并缓存
self.downloadAndCacheImageWithURL(resource.downloadURL,
forKey: resource.cacheKey,
retrieveImageTask: task,
progressBlock: progressBlock,
completionHandler: diskTaskCompletionHandler,
options: options,
targetCache: targetCache,
downloader: downloader)
}
}
)
task.diskRetrieveTask = diskTask
}
return task
}
几个重要的点我加了中文注释，应该很好理解。现在先来看一下parseOptionsInfo这个方法，它是用来解析optionsInfo的：
func parseOptionsInfo(optionsInfo: KingfisherOptionsInfo?) -> (Options, ImageCache, ImageDownloader) {
//3个默认值
var options = KingfisherManager.DefaultOptions
var targetCache = self.cache
var targetDownloader = self.downloader
//用户没有指定的话则使用默认下载器、默认缓存器和默认配置。
guard let optionsInfo = optionsInfo else {
return (options, targetCache, targetDownloader)
}
//匹配各个枚举类型，进行分别处理。扩展方法kf-findFirstMatch和重载运算符“==”配合，写得很优雅(把"=="换成自定义其他操作符就更好了，"=="有点不符合直觉)。
if let optionsItem = optionsInfo.kf_findFirstMatch(.Options(.None)), case .Options(let optionsInOptionsInfo) = optionsItem {
//如果选项包含后台回调，则使用一个新线程，否则使用默认queue（主线程）
let queue = optionsInOptionsInfo.contains(KingfisherOptions.BackgroundCallback) ? dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0) : KingfisherManager.DefaultOptions.queue
//默认比例是1
let scale = optionsInOptionsInfo.contains(KingfisherOptions.ScreenScale) ? UIScreen.mainScreen().scale : KingfisherManager.DefaultOptions.scale
//打包options
options = (forceRefresh: optionsInOptionsInfo.contains(KingfisherOptions.ForceRefresh),
lowPriority: optionsInOptionsInfo.contains(KingfisherOptions.LowPriority),
cacheMemoryOnly: optionsInOptionsInfo.contains(KingfisherOptions.CacheMemoryOnly),
shouldDecode: optionsInOptionsInfo.contains(KingfisherOptions.BackgroundDecode),
queue: queue, scale: scale)
}
if let optionsItem = optionsInfo.kf_findFirstMatch(.TargetCache(self.cache)), case .TargetCache(let cache) = optionsItem {
targetCache = cache
}
if let optionsItem = optionsInfo.kf_findFirstMatch(.Downloader(self.downloader)), case .Downloader(let downloader) = optionsItem {
targetDownloader = downloader
}
return (options, targetCache, targetDownloader)
}
其中：
if let optionsItem = optionsInfo.kf_findFirstMatch(.Options(.None)), case .Options(let optionsInOptionsInfo) = optionsItem
这个写法让我一时没反应过来，愣了好一会儿，后来想起来在WWDC视频上看到过Swfit2关于模式匹配的一些新内容，喵神的写法应该是跟下面这个写法等效的，只是喵神的更加简洁优雅：
if let optionsItem = optionsInfo.kf_findFirstMatch(.Options(.None)) {
switch optionsItem {
case .Options(let optionsInOptionsInfo):
let queue = ...
...
}
}
我把源代码注释掉，改成上面这种形式跑了一下，发现没有问题。
然后kf_findFirstMatch(.Options(.None)这个方法又让我纠结了一阵，它是对CollectionType的一个扩展(给协议加扩展方法也是Swift2新特性)，长这样的：
extension CollectionType where Generator.Element == KingfisherOptionsInfoItem {
func kf_findFirstMatch(target: Generator.Element) -> Generator.Element? {
//取得target的索引
let index = indexOf {
e in
//这个"=="，上面已经重载过了，只要类型相等就返回true，所以如果target是.Options(.None)，e只要是.Options(_)都可以匹配，返回.Options(_)的索引
return e == target
}
return (index != nil) ? self[index!] : nil
}
}
现在我加了注释大家应该看得明白了，这个函数会返回跟target同类型的元素的索引。之前我想当然地认为这个函数应该返回跟target相等元素的索引，比如kf_findFirstMatch(.Options(.None)，应该要返回匹配到的.Options(.None)的索引，然而实际上，只要匹配到任意一个.Options(_)，就可以返回它的索引了。因为==被这样重载了：
func == (a: KingfisherOptionsInfoItem, b: KingfisherOptionsInfoItem) -> Bool {
switch (a, b) {
case (.Options(_), .Options(_)): return true
case (.TargetCache(_), .TargetCache(_)): return true
case (.Downloader(_), .Downloader(_)): return true
case (.Transition(_), .Transition(_)): return true
default: return false
}
}
怎么说呢，总觉得不太符合直觉，索性自定义一个新的运算符可能更合适些，不容易造成误解。
好了，接着往下看retrieveImageWithResource这个方法。取得了options、targetCache和downloader之后，就要判断用户是否指定强制刷新，如果是则直接联网下载，否则先从缓存中取数据，若没有缓存再联网下载。这一段我个人认为也稍微有点不符合直觉（我真不是处女座），喵神把“联网下载”那一段逻辑单独封装成一个方法，因为就算不需要强制刷新，但缓存中若没有数据的话，在“从缓存中取数据”这个任务的结束闭包中也还要进行下载操作，所以显然可以把“联网下载”的逻辑提取出来进行复用。这样子的话，“联网下载”被提取成一个方法，方法名清晰易懂，但“提取缓存”却还有那么一大段在那儿，显得不太对称。要是把提取缓存也封装成一个方法，然后在retrieveImageWithResource里调用，可能可读性更好一些：
if options.forceRefresh {
//若用户指定强制刷新则直接联网下载并缓存
downloadAndCacheImageWithURL(resource.downloadURL,
forKey: resource.cacheKey,
retrieveImageTask: task,
progressBlock: progressBlock,
completionHandler: completionHandler,
options: options,
targetCache: targetCache,
downloader: downloader)
} else {
//不强制刷新则尝试从缓存中取，若无缓存则联网下载并缓存
tryToRetrieveImageFromCacheForKey(resource.cacheKey,
withURL: resource.downloadURL,
retrieveImageTask: task,
progressBlock: progressBlock,
completionHandler: completionHandler,
options: options,
targetCache: targetCache,
downloader: downloader)
}
相应地，tryToRetrieveImageFromCacheForKey长这样：
func tryToRetrieveImageFromCacheForKey(key: String,
withURL URL: NSURL,
retrieveImageTask: RetrieveImageTask,
progressBlock: DownloadProgressBlock?,
completionHandler: CompletionHandler?,
options: Options,
targetCache: ImageCache,
downloader: ImageDownloader)
{
let diskTaskCompletionHandler: CompletionHandler = { (image, error, cacheType, imageURL) -> () in
// Break retain cycle created inside diskTask closure below
//完成之后取消任务引用，避免循环引用，释放内存
retrieveImageTask.diskRetrieveTask = nil
completionHandler?(image: image, error: error, cacheType: cacheType, imageURL: imageURL)
}
let diskTask = targetCache.retrieveImageForKey(key, options: options,
completionHandler: { image, cacheType in
if image != nil {
diskTaskCompletionHandler(image: image, error: nil, cacheType:cacheType, imageURL: URL)
} else {
//没有缓存则联网下载并缓存
self.downloadAndCacheImageWithURL(URL,
forKey: key,
retrieveImageTask: retrieveImageTask,
progressBlock: progressBlock,
completionHandler: diskTaskCompletionHandler,
options: options,
targetCache: targetCache,
downloader: downloader)
}
}
)
retrieveImageTask.diskRetrieveTask = diskTask
}
到这里为止，我们对Kingfisher对整体架构已经有比较清晰的认识了，大概是这个样子：
Kingfisher.png
喵神是我第一个知道的iOS领域的大牛，我是从后端转iOS的嘛，之前看完苹果官方的《The Swift Programming Language》之后，就入手了喵神的《Swifter》，看完受益匪浅。最近想找点优秀的源码读一读，第一时间就想到了Kingfisher。其实之前我并没有用过这个库（因为要兼容iOS7），在项目中只是自己简单封装了一下异步下载和缓存的过程，而且我只做了内存缓存，虽然勉强够用了，但看了Kingfisher之后实在是觉得自己写得非常简陋。读完了之后忍不住想记录下来，先小结一下读了上面这部分的收获吧：
- 在系统设计方面有了一点心得
- 对软件项目的规范也有了直接的体会（我身边没有人给我这方面的指点，一直都是看书跟自己摸索）
- Swift中关于
enum和模式匹配的优雅用法让我印象深刻
接下来我会继续写一下阅读下载模块和缓存模块的过程，下载模块中用到了很多GCD的新特性，缓存模块主要是文件操作和对不同格式图片的解码操作等等，都非常值得学习。
下一篇地址：Kingfisher源码阅读（二）
