Kingfisher — چیست، مفاهیم کلیدی و ImageCache

Kingfisher چیست؟

Kingfisher — کتابخانه‌ای برای بارگذاری ناهمگام و ذخیره‌سازی تصاویر در پلتفرم‌های Apple، که کاملاً به زبان Swift نوشته شده است. نویسنده کتابخانه Wei Wang (onevcat) است. Kingfisher مجموعه‌ای از ابزارها را برای بارگذاری تصاویر از شبکه با ذخیره‌سازی خودکار، تغییر شکل‌ها و پشتیبانی از فناوری‌های مدرن Swift: async/await، Combine، Sendable ارائه می‌دهد.

این کتابخانه بیش از 23٠۰۰ ستاره در 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، به طور خودکار در هشدار حافظه پاک می‌شود
• Disk Cache — ذخیره‌سازی فایل با TTL و بررسی محدودیت اندازه
• ImageDownloader — مبتنی بر URLSession با پشتیبانی از تغییر درخواست از طریق اصلاح‌کننده‌ها

Swift Concurrency

از نسخه 7.0، Kingfisher به طور کامل از async/await پشتیبانی می‌کند. روش retrieveImage به عنوان یک تابع ناهمگام در دسترس است که بدون بلاک‌های تکمیلی مستقیماً Result برمی‌گرداند. این امکان استفاده از کتابخانه را در معماری‌های مدرن Swift با Structured Concurrency فراهم می‌کند.

ماژول‌های اصلی Kingfisher

Kingfisher به چندین ماژول تقسیم شده است که هر کدام وظیفه خود را حل می‌کند. این تقسیم‌بندی آزمایش و جایگزینی مؤلفه‌ها را ساده می‌کند.

KingfisherManager

KingfisherManager — نمای facade که بارگذاری، کش و پردازشگرها را ترکیب می‌کند. به طور پیش‌فرض از singleton KingfisherManager.shared استفاده می‌شود، اما می‌توان یک نمونه جداگانه با تنظیمات سفارشی برای سناریوهای ایزوله (مثلاً برای تست‌های واحد) ایجاد کرد.

ImageCache

ImageCache — کش دو سطحی با تنظیمات جداگانه برای حافظه و دیسک. Memory Cache محدودیتی در تعداد اشیاء ندارد، اما در صورت کمبود حافظه توسط سیستم پاک می‌شود. Disk Cache فایل‌ها را در دایرکتوری با تنظیمات TTL (پیش‌فرض ۷ روز)، محدودیت اندازه (پیش‌فرض ۰ — بدون محدودیت) و پاک‌سازی خودکار ذخیره می‌کند.

ImageProcessor

ImageProcessor — پروتکلی با یک متد process(item:options:) که تصویر پردازش شده را برمی‌گرداند. پیاده‌سازی‌های داخلی: ResizingImageProcessor (تغییر اندازه)، RoundCornerImageProcessor (گرد کردن)، BlurImageProcessor (محو کردن گاوسی)، OverlayImageProcessor (افزودن رنگ). پردازشگرها را می‌توان با عملگر |> ترکیب کرد.

سیستم ذخیره‌سازی Kingfisher

معماری کش Kingfisher بر اساس اصل write-through است: داده‌ها همزمان در هر دو سطح نوشته می‌شوند و خواندن از سریع‌ترین سطح — حافظه — شروع می‌شود. کلید کش URL مطلق تصویر پس از حذف پارامترهای جستجو است.

برای مدیریت اندازه Disk Cache از محاسبه اندازه کل فایل‌ها با مرتب‌سازی بر اساس تاریخ آخرین دسترسی استفاده می‌شود. هنگام تجاوز از حد، فایل‌هایی با قدیمی‌ترین تاریخ دسترسی حذف می‌شوند تا اندازه به زیر ۵۰٪ حد برسد. پاک‌سازی TTL در هنگام مقداردهی کش و هر بار فراخوانی cleanExpired انجام می‌شود.

نمونه‌های استفاده از Kingfisher در Swift

Kingfisher چندین رابط برای بارگذاری تصاویر ارائه می‌دهد: افزونه روی UIImageView، مدیر جداگانه و SwiftUI View.

بارگذاری در UIImageView از طریق kf

kf — ویژگی فضای نام در 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 بدون 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 شامل 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 در مقابل 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 نصب می‌شود. پس از نصب کافی است ماژول را import کرده و هر متد بارگذاری را فراخوانی کنید — کتابخانه بدون پیکربندی اضافی آماده کار است.

// مدیر بسته Swift (Package.swift)
dependencies: [
    .package(
        url: "https://github.com/onevcat/Kingfisher.git",
        from: "7.12.0"
    )
]

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

برای سفارشی‌سازی تنظیمات سراسری از KingfisherManager.shared استفاده می‌شود. می‌توان timeout بارگذار، استراتژی کش و پردازشگرهای پیش‌فرض را تغییر داد. در زیر نمونه پیکربندی کش ۵۰۰ MB با TTL ۱۴ روز آورده شده است.

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 سفارشی با timeoutها، هدرها و سیاست‌های کش تنظیم کرد. برای نظارت بر پیشرفت، ماژول KFIndicator با پشتیبانی از ActivityIndicator، ProgressView و نشانگرهای سفارشی در دسترس است.