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-based, автоматически очищается при memory warning
• Disk Cache — файловое хранилище с TTL и проверкой лимита размера
• ImageDownloader — URLSession-based с поддержкой модификации запроса через модификаторы

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("Loaded \(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("Failed: \(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 и кастомных индикаторов.