Kingfisher源码导读

Sources/
├── General/        # KingfisherManager, KingfisherOptionsInfo, Resource, Source
├── Networking/     # ImageDownloader, SessionDelegate, ImagePrefetcher
├── Cache/          # ImageCache, MemoryStorage, DiskStorage
├── Image/          # ImageProcessor, 图片格式处理, 滤镜
├── Extensions/     # UIKit/AppKit 扩展 (ImageView+Kingfisher, UIButton+Kingfisher)
├── SwiftUI/        # KFImage, KFAnimatedImage, ImageBinder
├── Views/          # AnimatedImageView
└── Utility/        # 辅助工具类

public struct KingfisherWrapper<Base>: @unchecked Sendable {
    public let base: Base
    public init(_ base: Base) {
        self.base = base
    }
}

public protocol KingfisherCompatible: AnyObject { }

extension KingfisherCompatible {
    public var kf: KingfisherWrapper<Self> {
        get { return KingfisherWrapper(self) }
        set { }
    }
}

extension KFCrossPlatformImage: KingfisherCompatible { }
extension KFCrossPlatformImageView: KingfisherCompatible { }
extension KFCrossPlatformButton: KingfisherCompatible { }

imageView.kf.setImage(with: url)

public class KingfisherManager: @unchecked Sendable {
    public static let shared = KingfisherManager()
    
    private var _cache: ImageCache
    private var _downloader: ImageDownloader
    
    public var cache: ImageCache {
        get { propertyQueue.sync { _cache } }
        set { propertyQueue.sync { _cache = newValue } }
    }
    
    public var downloader: ImageDownloader {
        get { propertyQueue.sync { _downloader } }
        set { propertyQueue.sync { _downloader = newValue } }
    }
    
    private let processingQueue: CallbackQueue
    private let propertyQueue = DispatchQueue(label: "com.onevcat.Kingfisher.KingfisherManagerPropertyQueue")
}

private func retrieveImage(
    with source: Source,
    context: RetrievingContext,
    downloadTaskUpdated: DownloadTaskUpdatedBlock?,
    completionHandler: (@Sendable (Result<RetrieveImageResult, KingfisherError>) -> Void)?
) -> DownloadTask? {
    let options = context.options
    if options.forceRefresh {
        // 强制刷新：跳过缓存直接下载
        return loadAndCacheImage(source: source, context: context,
                                 completionHandler: completionHandler)?.value
    } else {
        // 先查缓存
        let loadedFromCache = retrieveImageFromCache(
            source: source, context: context,
            downloadTaskUpdated: downloadTaskUpdated,
            completionHandler: completionHandler)
        if loadedFromCache { return nil }
        
        if options.onlyFromCache {
            // 仅允许从缓存加载，但缓存未命中
            let error = KingfisherError.cacheError(reason: .imageNotExisting(key: source.cacheKey))
            completionHandler?(.failure(error))
            return nil
        }
        // 缓存未命中，发起下载
        return loadAndCacheImage(source: source, context: context,
                                 completionHandler: completionHandler)?.value
    }
}

let coordinator = CacheCallbackCoordinator(
    shouldWaitForCache: options.waitForCache,
    shouldCacheOriginal: needToCacheOriginalImage)

// 缓存处理后的图片
targetCache.store(value.image, original: value.originalData,
                  forKey: source.cacheKey, options: options,
                  toDisk: !options.cacheMemoryOnly) { _ in
    coordinator.apply(.cachingImage) {
        completionHandler?(.success(result))
    }
}

// 如需缓存原图
if needToCacheOriginalImage {
    originalCache.storeToDisk(value.originalData, forKey: source.cacheKey,
                              processorIdentifier: DefaultImageProcessor.default.identifier,
                              expiration: options.diskCacheExpiration) { _ in
        coordinator.apply(.cachingOriginalImage) {
            completionHandler?(.success(result))
        }
    }
}

coordinator.apply(.cacheInitiated) {
    completionHandler?(.success(result))
}

public func retrieveImage(
    with source: Source,
    options: KingfisherOptionsInfo? = nil,
    progressBlock: DownloadProgressBlock? = nil
) async throws -> RetrieveImageResult {
    // ...
    let task = CancellationDownloadTask()
    return try await withTaskCancellationHandler {
        try await withCheckedThrowingContinuation { continuation in
            let downloadTask = retrieveImage(with: source, ...) { result in
                safeResume(with: result)
            }
            // ...
        }
    } onCancel: {
        Task { await task.task?.cancel() }
    }
}

open class ImageCache: @unchecked Sendable {
    public static let `default` = ImageCache(name: "default")
    
    public let memoryStorage: MemoryStorage.Backend<KFCrossPlatformImage>
    public let diskStorage: DiskStorage.Backend<Data>
    private let ioQueue: DispatchQueue
}

class StorageObject<T> {
    var value: T?
    let expiration: StorageExpiration
    private(set) var estimatedExpiration: Date
    
    var isExpired: Bool {
        return estimatedExpiration.isPast
    }
    
    func extendExpiration(_ extendingExpiration: ExpirationExtending) {
        switch extendingExpiration {
        case .none: return
        case .cacheTime:
            self.estimatedExpiration = expiration.estimatedExpirationSinceNow
        case .expirationTime(let expirationTime):
            self.estimatedExpiration = expirationTime.estimatedExpirationSinceNow
        }
    }
}

class BackgroundKeepingStorageObject<T>: StorageObject<T>, NSDiscardableContent {
    var accessing = true
    func beginContentAccess() -> Bool {
        if value != nil { accessing = true } else { accessing = false }
        return accessing
    }
    func endContentAccess() { accessing = false }
    func discardContentIfPossible() { value = nil }
    func isContentDiscarded() -> Bool { return value == nil }
}

let notifications: [(Notification.Name, Selector)] = [
    (UIApplication.didReceiveMemoryWarningNotification, #selector(clearMemoryCache)),
    (UIApplication.willTerminateNotification, #selector(cleanExpiredDiskCache)),
    (UIApplication.didEnterBackgroundNotification, #selector(backgroundCleanExpiredDiskCache))
]

@MainActor @objc public func backgroundCleanExpiredDiskCache() {
    guard let sharedApplication = KingfisherWrapper<UIApplication>.shared else { return }
    let createdTask = sharedApplication.beginBackgroundTask(
        withName: "Kingfisher:backgroundCleanExpiredDiskCache",
        expirationHandler: endBackgroundTaskIfNeeded)
    cleanExpiredDiskCache { endBackgroundTaskIfNeeded() }
}

open func retrieveImage(forKey key: String, options: KingfisherParsedOptionsInfo, ...) {
    // 1. 先查内存
    if let image = retrieveImageInMemoryCache(forKey: key, options: options) {
        completionHandler(.success(.memory(image)))
    }
    // 2. fromMemoryCacheOrRefresh 模式下只查内存
    else if options.fromMemoryCacheOrRefresh {
        completionHandler(.success(.none))
    }
    // 3. 查磁盘
    else {
        retrieveImageInDiskCache(forKey: key, options: options) { outcome in
            switch outcome {
            case .image(let image):
                // 从磁盘取出后回写到内存缓存
                self.store(image, forKey: key, options: cacheOptions, toDisk: false) { _ in
                    completionHandler(.success(.disk(image)))
                }
            case .notFound, .stale:
                completionHandler(.success(.none))
            }
        }
    }
}

func retrieveImageInDiskCache(forKey key: String, options: ..., outcomeHandler: ...) {
    loadingQueue.execute {
        // CHECK 1: 入队等待期间任务已过时
        if options.isSourceTaskStale {
            outcomeHandler(.success(.stale))
            return
        }
        // ... 磁盘读取 ...
        // CHECK 2: 磁盘读取完成但反序列化前
        if options.isSourceTaskStale {
            outcomeHandler(.success(.stale))
            return
        }
        // ... 反序列化 ...
        // CHECK 3: 反序列化后、后台解码前
        if image != nil, options.isSourceTaskStale {
            outcomeHandler(.success(.stale))
            return
        }
    }
}

open class ImageDownloader: @unchecked Sendable {
    public static let `default` = ImageDownloader(name: "default")
    
    open var downloadTimeout: TimeInterval = 15.0  // 默认超时 15 秒
    open var sessionConfiguration = URLSessionConfiguration.ephemeral
    open var sessionDelegate: SessionDelegate
    open var requestsUsePipelining = false
    open weak var delegate: (any ImageDownloaderDelegate)?
    open weak var authenticationChallengeResponder: (any AuthenticationChallengeResponsible)?
    
    private var session: URLSession
}

private func addDownloadTask(context: DownloadingContext, callback: SessionDataTask.TaskCallback) -> DownloadTask {
    lock.lock()
    defer { lock.unlock() }
    
    if let existingTask = sessionDelegate.task(for: context.url) {
        // URL 已有正在进行的任务，复用它
        downloadTask = sessionDelegate.append(existingTask, callback: callback)
    } else {
        // 新建 URLSession dataTask
        let sessionDataTask = session.dataTask(with: context.request)
        sessionDataTask.priority = context.options.downloadPriority
        downloadTask = sessionDelegate.add(sessionDataTask, url: context.url, callback: callback)
    }
    return downloadTask
}

sessionTask.onTaskDone.delegate(on: self) { (self, done) in
    let (result, callbacks) = done
    
    switch result {
    case .success(let (data, response)):
        // 使用 ImageDataProcessor 对每个 callback 分别处理
        let processor = ImageDataProcessor(data: data, callbacks: callbacks,
                                            processingQueue: context.options.processingQueue)
        processor.onImageProcessed.delegate(on: self) { (self, done) in
            let (result, callback) = done
            let imageResult = result.map {
                ImageLoadingResult(image: $0, url: context.url, originalData: data,
                                   metrics: sessionTask?.metrics)
            }
            callback.options.callbackQueue.execute {
                callback.onCompleted?.call(imageResult)
            }
        }
        processor.process()
        
    case .failure(let error):
        callbacks.forEach { callback in
            callback.options.callbackQueue.execute {
                callback.onCompleted?.call(.failure(error))
            }
        }
    }
}

public final class DownloadTask: @unchecked Sendable {
    public private(set) var sessionTask: SessionDataTask?
    public private(set) var cancelToken: SessionDataTask.CancelToken?
    
    public func cancel() {
        guard let sessionTask, let cancelToken else { return }
        sessionTask.cancel(token: cancelToken)
    }
}

guard let requestModifier = options.requestModifier else {
    checkRequestAndDone(r: request)
    return
}
if let m = requestModifier as? any ImageDownloadRequestModifier {
    guard let result = m.modified(for: request) else {
        done(.failure(KingfisherError.requestError(reason: .emptyRequest)))
        return
    }
    checkRequestAndDone(r: result)
}

public protocol ImageProcessor: Sendable {
    var identifier: String { get }
    func process(item: ImageProcessItem, options: KingfisherParsedOptionsInfo) -> KFCrossPlatformImage?
}

infix operator |>: AdditionPrecedence

public func |>(left: any ImageProcessor, right: any ImageProcessor) -> any ImageProcessor {
    return left.append(another: right)
}

extension ImageProcessor {
    public func append(another: any ImageProcessor) -> any ImageProcessor {
        let newIdentifier = identifier.appending("|>\(another.identifier)")
        return GeneralProcessor(identifier: newIdentifier) { item, options in
            if let image = self.process(item: item, options: options) {
                return another.process(item: .image(image), options: options)
            } else {
                return nil
            }
        }
    }
}

let processor = DownsamplingImageProcessor(size: CGSize(width: 100, height: 100))
                |> RoundCornerImageProcessor(cornerRadius: 20)

// DownsamplingImageProcessor 的实现
public func process(item: ImageProcessItem, options: KingfisherParsedOptionsInfo) -> KFCrossPlatformImage? {
    switch item {
    case .image(let image):
        guard let data = image.kf.data(format: .unknown) else { return nil }
        return KingfisherWrapper.downsampledImage(data: data, to: size, scale: options.scaleFactor)
    case .data(let data):
        return KingfisherWrapper.downsampledImage(data: data, to: size, scale: options.scaleFactor)
    }
}

imageView.kf.setImage(with: url)

KFImage(URL(string: "https://example.com/image.jpg"))
    .placeholder { ProgressView() }
    .resizable()
    .aspectRatio(contentMode: .fit)
    .frame(width: 200, height: 200)

// UIKit
KF.url(imageURL)
    .processor(DownsamplingImageProcessor(size: CGSize(width: 100, height: 100)))
    .cacheOriginalImage()
    .set(to: imageView)

// SwiftUI
KF.url(imageURL)
    .processor(DownsamplingImageProcessor(size: CGSize(width: 100, height: 100)))
    .cacheOriginalImage()
    .toSwiftUI()

public class KingfisherManager: @unchecked Sendable {
    private let propertyQueue = DispatchQueue(label: "com.onevcat.Kingfisher.KingfisherManagerPropertyQueue")
    
    public var cache: ImageCache {
        get { propertyQueue.sync { _cache } }
        set { propertyQueue.sync { _cache = newValue } }
    }
}

private func addDownloadTask(...) -> DownloadTask {
    lock.lock()
    defer { lock.unlock() }
    // 操作 sessionDelegate 的任务字典
}

public typealias DownloadTaskUpdatedBlock = (@Sendable (_ newTask: DownloadTask?) -> Void)

public typealias DownloadProgressBlock = ((_ receivedSize: Int64, _ totalSize: Int64) -> Void)

actor CancellationDownloadTask {
    var task: DownloadTask?
    func setTask(_ task: DownloadTask?) { self.task = task }
}