Kingfisher — cos'è, concetti chiave e ImageCache

Cos'è Kingfisher?

Kingfisher è una libreria per il caricamento asincrono e la memorizzazione nella cache di immagini sulle piattaforme Apple, scritta interamente in Swift. L'autore della libreria è Wei Wang (onevcat). Kingfisher fornisce una serie di strumenti per caricare immagini dalla rete con cache automatica, trasformazioni e supporto per le moderne tecnologie Swift: async/await, Combine, Sendable.

La libreria ha oltre 23.000 stelle su GitHub ed è utilizzata in applicazioni come Telegram, Snapchat e Dropbox. Kingfisher supporta GIF, APNG, HEIF e tutti i formati di immagine standard. Ogni richiesta restituisce un Result type-safe, eliminando gli errori di conversione dei tipi.

L'architettura di Kingfisher è costruita su tre componenti principali: Manager (gestore dei download), Cache (cache a due livelli) e Processor (trasformazioni). Questi componenti sono collegati tramite protocolli, consentendo di sostituire qualsiasi parte senza modificare le dipendenze.

Come funziona Kingfisher: Manager e Cache

KingfisherManager è la classe centrale che coordina il caricamento, la memorizzazione nella cache e l'elaborazione delle immagini. Contiene riferimenti a ImageCache e ImageDownloader e fornisce un unico metodo retrieveImage che restituisce l'immagine pronta dopo aver attraversato tutte le fasi.

Processo di caricamento

Quando si chiama retrieveImage, il Manager controlla prima il Memory Cache — un NSCache con UIImage, dove la chiave è formata dall'URL di origine e dal CacheSerializer. Se l'immagine viene trovata, viene restituita immediatamente. In caso di mancata corrispondenza, viene controllato il Disk Cache — lettura dal filesystem con decrittografia tramite serializzatore. Se la cache su disco è vuota, viene effettuata una richiesta di rete tramite ImageDownloader, il risultato viene decodificato, trasformato e salvato in entrambi i livelli di cache.

• Memory Cache — basato su NSCache, cancellato automaticamente in caso di avviso di memoria
• Disk Cache — archiviazione file con TTL e controllo del limite di dimensione
• ImageDownloader — basato su URLSession con supporto per la modifica delle richieste tramite modificatori

Swift Concurrency

A partire dalla versione 7.0, Kingfisher supporta completamente async/await. Il metodo retrieveImage è disponibile come funzione asincrona, restituendo Result direttamente senza blocchi di completamento. Ciò consente di utilizzare la libreria nelle architetture Swift moderne con Structured Concurrency.

Moduli principali di Kingfisher

Kingfisher è divisa in diversi moduli, ciascuno dei quali risolve il proprio compito. Questa separazione semplifica i test e la sostituzione dei componenti.

KingfisherManager

KingfisherManager è una facciata che combina caricamento, cache e processori. Per impostazione predefinita, viene utilizzato il singleton KingfisherManager.shared, ma è possibile creare un'istanza separata con impostazioni personalizzate per scenari isolati (ad esempio, per test unitari).

ImageCache

ImageCache è una cache a due livelli con impostazioni separate per memoria e disco. Memory Cache non ha limiti sul numero di oggetti, ma il sistema lo cancella quando la memoria è scarsa. Disk Cache archivia i file in una directory con TTL configurabile (default 7 giorni), limite di dimensione (default 0 — nessun limite) e pulizia automatica.

ImageProcessor

ImageProcessor è un protocollo con un unico metodo process(item:options:) che restituisce l'immagine elaborata. Implementazioni integrate: ResizingImageProcessor (ridimensionamento), RoundCornerImageProcessor (arrotondamento), BlurImageProcessor (sfocatura gaussiana), OverlayImageProcessor (sovrapposizione colore). I processori possono essere combinati utilizzando l'operatore |>.

Sistema di cache di Kingfisher

L'architettura della cache di Kingfisher si basa sul principio write-through: i dati vengono scritti su entrambi i livelli contemporaneamente e la lettura inizia dal livello più veloce — la memoria. La chiave della cache è l'URL assoluto dell'immagine dopo la rimozione dei parametri di query.

Per gestire la dimensione del Disk Cache, viene calcolata la dimensione totale dei file ordinati per data dell'ultimo accesso. Quando il limite viene superato, i file con la data di accesso più vecchia vengono rimossi fino a quando la dimensione non scende al di sotto del 50% del limite. La pulizia TTL avviene durante l'inizializzazione della cache e ad ogni chiamata a cleanExpired.

Esempi di utilizzo di Kingfisher in Swift

Kingfisher fornisce diverse interfacce per caricare immagini: un'estensione su UIImageView, un gestore separato e una View SwiftUI.

Caricamento in UIImageView tramite kf

kf è una proprietà namespace su UIImageView che fornisce i metodi setImage, cancelDownload e gli indicatori di caricamento. Il metodo setImage accetta URLSource e i parametri opzionali Options e 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("Caricato \(receivedSize) / \(totalSize)")
    }
)

Il metodo restituisce un DownloadTask che supporta l'annullamento tramite cancel e il monitoraggio del progresso. Internamente, setImage chiama KingfisherManager.shared.retrieveImage con rilevamento automatico di ImageView come Target.

Utilizzo con async/await

A partire da Kingfisher 7.0, il metodo setImage è disponibile in una versione asincrona. Ciò consente di integrare il caricamento delle immagini in Swift Structured Concurrency senza callback.

func loadAvatar() async {
    do {
        let result = try await imageView.kf.setImage(
            with: url,
            options: [.processor(ResizingImageProcessor(
                targetSize: CGSize(width: 100, height: 100)
            ))]
        )
        // result.image contiene UIImage
    } catch {
        print("Fallito: \(error)")
    }
}

KFImage per SwiftUI

KFImage è una View SwiftUI, simile ad AsyncImage di iOS 15, ma con il supporto completo della cache di Kingfisher. La View utilizza automaticamente KingfisherManager.shared ma supporta un gestore personalizzato tramite il modificatore .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)
    }
}

Indicatori di caricamento in Kingfisher

Kingfisher fornisce un sistema di indicatori integrato per visualizzare lo stato di avanzamento del caricamento delle immagini. IndicatorType è un'enumerazione con tre opzioni: .activity (UIActivityIndicatorView), .progress (UIProgressView) e .custom (implementazione personalizzata del protocollo Indicator). L'indicatore appare automaticamente sopra ImageView durante il caricamento e si nasconde al termine.

Per un indicatore personalizzato, è necessario implementare il protocollo Indicator con i metodi startAnimatingView() e stopAnimatingView(). Ciò consente soluzioni ibride: uno scheletro con animazione shimmer, un'immagine segnaposto con rivelazione graduale o un logo con animazione di opacità. Kingfisher supporta anche l'impostazione globale dell'indicatore tramite KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

Sulla piattaforma iOS, Kingfisher e SDWebImage sono le due librerie dominanti per il caricamento di immagini. La scelta tra di esse dipende dal linguaggio del progetto, dai requisiti di prestazioni e dall'ecosistema.

Il vantaggio principale di Kingfisher è la sua architettura Swift-first: supporto completo per async/await, Combine Publishers, Sendable e tipi Result. SDWebImage mantiene la leadership grazie al suo ecosistema di plugin più ampio (WebP, SVG, MapKit) e al supporto per Objective-C.

Configurazione di Kingfisher in un progetto iOS

Kingfisher viene installato tramite Swift Package Manager, CocoaPods o Carthage. Dopo l'installazione, basta importare il modulo e chiamare qualsiasi metodo di caricamento — la libreria è pronta all'uso senza configurazione aggiuntiva.

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

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

Per personalizzare le impostazioni globali, si utilizza KingfisherManager.shared. È possibile modificare il timeout del downloader, la strategia di cache e i processori predefiniti. Di seguito è riportato un esempio di configurazione di una cache da 500 MB con TTL di 14 giorni.

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 viene configurato anche tramite il gestore: è possibile impostare una URLSessionConfiguration personalizzata con timeout, intestazioni e politiche di cache. Per il monitoraggio del progresso, è disponibile il modulo KFIndicator con supporto per ActivityIndicator, ProgressView e indicatori personalizzati.