Kingfisher — що це, ключові поняття та ImageCache

Що таке Kingfisher?

Kingfisher — бібліотека для асинхронного завантаження та кешування зображень на платформах Apple, написана повністю на Swift. Автор бібліотеки — Wei Wang (onevcat). Kingfisher надає набір інструментів для завантаження зображень з мережі з автоматичним кешуванням, трансформаціями та підтримкою сучасних Swift-технологій: async/await, Combine, Sendable.

Бібліотека має понад 23 000 зірок на GitHub та використовується в таких додатках, як Telegram, Snapchat та Dropbox. Kingfisher підтримує GIF, APNG, HEIF та всі стандартні формати зображень. Кожен запит повертає типобезпечний Result, що виключає помилки приведення типів.

Архітектура Kingfisher побудована на трьох основних компонентах: Manager (менеджер завантажень), Cache (дворівневий кеш) та Processor (трансформації). Ці компоненти пов'язані через протоколи, що дозволяє замінювати будь-яку частину без зміни залежностей.

Як працює Kingfisher: Manager та Cache

KingfisherManager — центральний клас, що координує завантаження, кешування та обробку зображень. Він містить посилання на ImageCache та ImageDownloader і надає єдиний метод retrieveImage, який повертає готове зображення після проходження всіх етапів.

Процес завантаження

При виклику retrieveImage Manager спочатку перевіряє Memory Cache — NSCache з UIImage, де ключ формується з URL джерела та CacheSerializer. Якщо зображення знайдено — воно повертається негайно. При промаху перевіряється Disk Cache — читання з файлової системи з дешифруванням через serializer. Якщо кеш на диску порожній — виконується мережевий запит через ImageDownloader, результат декодується, трансформується та зберігається в обидва рівні кешу.

• Memory Cache — NSCache-оснований, автоматично очищується при memory warning
• Disk Cache — файлове сховище з TTL та перевіркою ліміту розміру
• ImageDownloader — URLSession-оснований з підтримкою модифікації запиту через модифікатори

Swift Concurrency

Починаючи з версії 7.0, Kingfisher повністю підтримує async/await. Метод retrieveImage доступний як асинхронна функція, що повертає Result безпосередньо без completion-блоків. Це дозволяє використовувати бібліотеку в сучасних Swift-архітектурах з Structured Concurrency.

Основні модулі Kingfisher

Kingfisher розділена на кілька модулів, кожен з яких вирішує своє завдання. Такий розподіл спрощує тестування та заміну компонентів.

KingfisherManager

KingfisherManager — фасад, що об'єднує завантаження, кеш та процесори. За замовчуванням використовується синглтон KingfisherManager.shared, але можна створити окремий екземпляр з кастомними налаштуваннями для ізольованих сценаріїв (наприклад, для модульних тестів).

ImageCache

ImageCache — дворівневий кеш з окремими налаштуваннями для пам'яті та диска. Memory Cache не має обмеження за кількістю об'єктів, але очищається системою при нестачі пам'яті. Disk Cache зберігає файли в директорії з налаштуваннями TTL (за замовчуванням 7 днів), лімітом розміру (за замовчуванням 0 — без обмеження) та автоматичним очищенням.

ImageProcessor

ImageProcessor — протокол з єдиним методом process(item:options:), що повертає оброблене зображення. Вбудовані реалізації: ResizingImageProcessor (зміна розміру), RoundCornerImageProcessor (заокруглення), BlurImageProcessor (розмиття за Гауссом), OverlayImageProcessor (накладання кольору). Процесори можна комбінувати через оператор |>.

Система кешування Kingfisher

Архітектура кешу Kingfisher заснована на принципі write-through: дані записуються в обидва рівні одночасно, а читання починається з найшвидшого рівня — пам'яті. Ключем кешу є абсолютний URL зображення після видалення query-параметрів.

Для управління розміром Disk Cache використовується обчислення загального розміру файлів з сортуванням за датою останнього доступу. При перевищенні ліміту видаляються файли з найстарішою датою доступу, поки розмір не стане нижче 50% від ліміту. TTL-очищення відбувається при ініціалізації кешу та при кожному виклику cleanExpired.

Приклади використання Kingfisher у Swift

Kingfisher надає кілька інтерфейсів для завантаження зображень: extension на UIImageView, окремий менеджер та SwiftUI View.

Завантаження в UIImageView через kf

kf — namespace-властивість на UIImageView, що надає методи setImage, cancelDownload та індикатори завантаження. Метод setImage приймає URLSource та опціональні параметри Options і completionHandler.

import Kingfisher

imageView.kf.setImage(
    with: URL(string: "https://example.com/image.jpg"),
    placeholder: UIImage(named: "placeholder"),
    options: [
        .processor(RoundCornerImageProcessor(radius: .point(12))),
        .transition(.fade(0.3)),
        .cacheMemoryOnly
    ],
    progressBlock: { receivedSize, totalSize in
        print("Завантажено \(receivedSize) / \(totalSize)")
    }
)

Метод повертає DownloadTask, який підтримує скасування через cancel та відстеження прогресу. Всередині setImage викликає KingfisherManager.shared.retrieveImage з автоматичним визначенням ImageView як Target.

Використання з async/await

Починаючи з Kingfisher 7.0, метод setImage доступний в асинхронній версії. Це дозволяє інтегрувати завантаження зображень у Swift Structured Concurrency без колбеків.

func loadAvatar() async {
    do {
        let result = try await imageView.kf.setImage(
            with: url,
            options: [.processor(ResizingImageProcessor(
                targetSize: CGSize(width: 100, height: 100)
            ))]
        )
        // result.image містить UIImage
    } catch {
        print("Помилка: \(error)")
    }
}

KFImage для SwiftUI

KFImage — SwiftUI View, аналогічна AsyncImage з iOS 15, але з повною підтримкою кешування Kingfisher. View автоматично використовує KingfisherManager.shared, але підтримує кастомний менеджер через модифікатор .configure.

struct AvatarView: View {
    let url: URL

    var body: some View {
        KFImage(url)
            .placeholder { ProgressView() }
            .resizable()
            .fade(duration: 0.25)
            .forceTransition()
            .frame(width: 80, height: 80)
            .cornerRadius(40)
    }
}

Індикатори завантаження в Kingfisher

Kingfisher надає вбудовану систему індикаторів для відображення прогресу завантаження зображення. IndicatorType — перерахування з трьома варіантами: .activity (UIActivityIndicatorView), .progress (UIProgressView) та .custom (кастомна реалізація протоколу Indicator). Індикатор автоматично відображається поверх ImageView під час завантаження та ховається після завершення.

Для кастомного індикатора необхідно реалізувати протокол Indicator з методами startAnimatingView() та stopAnimatingView(). Це дозволяє використовувати гібридні рішення: скелет з анімацією shimmer, зображення-заглушку з поступовим проявленням або логотип з анімацією прозорості. Kingfisher також підтримує встановлення індикатора глобально через KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

На iOS-платформі Kingfisher та SDWebImage є двома домінуючими бібліотеками завантаження зображень. Вибір між ними залежить від мови проєкту, вимог до продуктивності та екосистеми.

Ключова перевага Kingfisher — Swift-first архітектура: повна підтримка async/await, Combine Publishers, Sendable та Result-типів. SDWebImage зберігає лідерство завдяки більш широкій екосистемі плагінів (WebP, SVG, MapKit) та підтримці Objective-C.

Налаштування Kingfisher у проєкті iOS

Kingfisher встановлюється через Swift Package Manager, CocoaPods або Carthage. Після встановлення достатньо імпортувати модуль та викликати будь-який метод завантаження — бібліотека готова до роботи без додаткової конфігурації.

// Swift Package Manager (Package.swift)
dependencies: [
    .package(
        url: "https://github.com/onevcat/Kingfisher.git",
        from: "7.12.0"
    )
]

// CocoaPods (Podfile)
pod 'Kingfisher', '~> 7.12'

Для кастомізації глобальних налаштувань використовується KingfisherManager.shared. Можна змінити таймаут завантажувача, кеш-стратегію та процесори за замовчуванням. Нижче приклад конфігурації кешу на 500 MB з TTL 14 днів.

let cache = ImageCache(name: "custom")
cache.memoryStorage.config.totalCostLimit = 100 * 1024 * 1024
cache.diskStorage.config.sizeLimit = 500 * 1024 * 1024
cache.diskStorage.config.expiration = .days(14)
KingfisherManager.shared.cache = cache

ImageDownloader також конфігурується через менеджер: можна задати кастомну URLSessionConfiguration з таймаутами, заголовками та політиками кешування. Для моніторингу прогресу доступний модуль KFIndicator з підтримкою ActivityIndicator, ProgressView та кастомних індикаторів.