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 και όλες τις τυπικές μορφές εικόνων. Κάθε αίτημα επιστρέφει ένα type-safe 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, καθαρίζεται αυτόματα σε προειδοποίηση μνήμης
• Disk Cache — αποθήκευση αρχείων με TTL και έλεγχο ορίου μεγέθους
• ImageDownloader — βασισμένο στο URLSession με υποστήριξη τροποποίησης αιτήματος μέσω τροποποιητών

Swift Concurrency

Από την έκδοση 7.0, το Kingfisher υποστηρίζει πλήρως το async/await. Η μέθοδος retrieveImage είναι διαθέσιμη ως ασύγχρονη συνάρτηση που επιστρέφει Result απευθείας χωρίς μπλοκ ολοκλήρωσης. Αυτό επιτρέπει τη χρήση της βιβλιοθήκης σε σύγχρονες αρχιτεκτονικές Swift με Structured Concurrency.

Κύριες ενότητες του Kingfisher

Το Kingfisher χωρίζεται σε πολλές ενότητες, καθεμία από τις οποίες επιλύει τη δική της εργασία. Αυτή η διαίρεση απλοποιεί τη δοκιμή και την αντικατάσταση στοιχείων.

KingfisherManager

KingfisherManager — μια πρόσοψη που συνδυάζει φόρτωση, προσωρινή μνήμη και επεξεργαστές. Από προεπιλογή, χρησιμοποιείται το singleton KingfisherManager.shared, αλλά μπορεί να δημιουργηθεί ξεχωριστό στιγμιότυπο με προσαρμοσμένες ρυθμίσεις για απομονωμένα σενάρια (π.χ. για δοκιμές μονάδας).

ImageCache

ImageCache — προσωρινή μνήμη δύο επιπέδων με ξεχωριστές ρυθμίσεις για μνήμη και δίσκο. Το Memory Cache δεν έχει όριο στον αριθμό αντικειμένων, αλλά καθαρίζεται από το σύστημα σε περίπτωση έλλειψης μνήμης. Το Disk Cache αποθηκεύει αρχεία σε έναν κατάλογο με ρυθμίσεις TTL (προεπιλογή 7 ημέρες), όριο μεγέθους (προεπιλογή 0 — χωρίς όριο) και αυτόματο καθαρισμό.

ImageProcessor

ImageProcessor — πρωτόκολλο με μία μόνο μέθοδο process(item:options:) που επιστρέφει την επεξεργασμένη εικόνα. Ενσωματωμένες υλοποιήσεις: ResizingImageProcessor (αλλαγή μεγέθους), RoundCornerImageProcessor (στρογγυλοποίηση), BlurImageProcessor (θόλωση Gauss), OverlayImageProcessor (προσθήκη χρώματος). Οι επεξεργαστές μπορούν να συνδυαστούν με τον τελεστή |>.

Σύστημα προσωρινής αποθήκευσης Kingfisher

Η αρχιτεκτονική προσωρινής μνήμης του Kingfisher βασίζεται στην αρχή write-through: τα δεδομένα γράφονται ταυτόχρονα και στα δύο επίπεδα και η ανάγνωση ξεκινά από το ταχύτερο επίπεδο — τη μνήμη. Το κλειδί προσωρινής μνήμης είναι το απόλυτο URL της εικόνας μετά την αφαίρεση παραμέτρων ερωτήματος.

Για τη διαχείριση του μεγέθους Disk Cache χρησιμοποιείται υπολογισμός συνολικού μεγέθους αρχείων με ταξινόμηση κατά ημερομηνία τελευταίας πρόσβασης. Κατά την υπέρβαση ορίου, τα αρχεία με την παλαιότερη ημερομηνία πρόσβασης διαγράφονται έως ότου το μέγεθος πέσει κάτω από το 50% του ορίου. Ο καθαρισμός TTL γίνεται κατά την προετοιμασία της προσωρινής μνήμης και σε κάθε κλήση cleanExpired.

Παραδείγματα χρήσης Kingfisher στο Swift

Το Kingfisher παρέχει πολλές διεπαφές για φόρτωση εικόνων: επέκταση στο 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 χωρίς callbacks.

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 και προσαρμοσμένων δεικτών.