Kingfisher — định nghĩa, khái niệm chính và ImageCache

Kingfisher là gì?

Kingfisher là thư viện tải và lưu trữ hình ảnh không đồng bộ trên các nền tảng Apple, được viết hoàn toàn bằng Swift. Tác giả của thư viện là Wei Wang (onevcat). Kingfisher cung cấp bộ công cụ để tải hình ảnh từ mạng với bộ nhớ đệm tự động, biến đổi và hỗ trợ các công nghệ Swift hiện đại: async/await, Combine, Sendable.

Thư viện có hơn 23.000 sao trên GitHub và được sử dụng trong các ứng dụng như Telegram, Snapchat và Dropbox. Kingfisher hỗ trợ GIF, APNG, HEIF và tất cả các định dạng hình ảnh tiêu chuẩn. Mỗi yêu cầu trả về Result an toàn kiểu dữ liệu, loại bỏ lỗi ép kiểu.

Kiến trúc của Kingfisher được xây dựng trên ba thành phần chính: Manager (trình quản lý tải xuống), Cache (bộ nhớ đệm hai cấp) và Processor (biến đổi). Các thành phần này được kết nối thông qua các giao thức, cho phép thay thế bất kỳ phần nào mà không thay đổi phụ thuộc.

Kingfisher hoạt động như thế nào: Manager và Cache

KingfisherManager là lớp trung tâm điều phối việc tải, lưu trữ và xử lý hình ảnh. Nó chứa tham chiếu đến ImageCache và ImageDownloader và cung cấp một phương thức duy nhất retrieveImage trả về hình ảnh đã sẵn sàng sau khi trải qua tất cả các bước.

Quy trình tải

Khi gọi retrieveImage, Manager đầu tiên kiểm tra Memory Cache — NSCache với UIImage, nơi khóa được hình thành từ URL nguồn và CacheSerializer. Nếu tìm thấy hình ảnh, nó được trả về ngay lập tức. Nếu không tìm thấy, kiểm tra Disk Cache — đọc từ hệ thống tệp với giải mã qua serializer. Nếu bộ nhớ đệm đĩa trống, một yêu cầu mạng được thực hiện qua ImageDownloader, kết quả được giải mã, biến đổi và lưu vào cả hai cấp bộ nhớ đệm.

• Memory Cache — dựa trên NSCache, tự động xóa khi có cảnh báo bộ nhớ
• Disk Cache — lưu trữ tệp với TTL và kiểm tra giới hạn kích thước
• ImageDownloader — dựa trên URLSession với hỗ trợ sửa đổi yêu cầu thông qua bộ sửa đổi

Swift Concurrency

Bắt đầu từ phiên bản 7.0, Kingfisher hỗ trợ đầy đủ async/await. Phương thức retrieveImage có sẵn dưới dạng hàm không đồng bộ, trả về Result trực tiếp mà không cần khối hoàn thành. Điều này cho phép sử dụng thư viện trong kiến trúc Swift hiện đại với Structured Concurrency.

Các mô-đun chính của Kingfisher

Kingfisher được chia thành nhiều mô-đun, mỗi mô-đun giải quyết một nhiệm vụ riêng. Sự phân chia này đơn giản hóa việc kiểm tra và thay thế thành phần.

KingfisherManager

KingfisherManager là mặt tiền kết hợp tải, bộ nhớ đệm và bộ xử lý. Theo mặc định, singleton KingfisherManager.shared được sử dụng, nhưng có thể tạo một phiên bản riêng với cài đặt tùy chỉnh cho các tình huống biệt lập (ví dụ: cho kiểm thử đơn vị).

ImageCache

ImageCache là bộ nhớ đệm hai cấp với cài đặt riêng cho bộ nhớ và đĩa. Memory Cache không có giới hạn về số lượng đối tượng, nhưng hệ thống sẽ xóa nó khi bộ nhớ thấp. Disk Cache lưu trữ tệp trong thư mục với TTL có thể cấu hình (mặc định 7 ngày), giới hạn kích thước (mặc định 0 — không giới hạn) và tự động dọn dẹp.

ImageProcessor

ImageProcessor là giao thức với một phương thức duy nhất process(item:options:) trả về hình ảnh đã xử lý. Các triển khai tích hợp: ResizingImageProcessor (thay đổi kích thước), RoundCornerImageProcessor (bo góc), BlurImageProcessor (làm mờ Gaussian), OverlayImageProcessor (lớp phủ màu). Các bộ xử lý có thể được kết hợp bằng toán tử |>.

Hệ thống bộ nhớ đệm của Kingfisher

Kiến trúc bộ nhớ đệm của Kingfisher dựa trên nguyên tắc write-through: dữ liệu được ghi đồng thời vào cả hai cấp và việc đọc bắt đầu từ cấp nhanh nhất — bộ nhớ. Khóa bộ nhớ đệm là URL tuyệt đối của hình ảnh sau khi loại bỏ các tham số truy vấn.

Để quản lý kích thước Disk Cache, tổng kích thước tệp được tính toán với sắp xếp theo ngày truy cập cuối cùng. Khi vượt quá giới hạn, các tệp có ngày truy cập cũ nhất sẽ bị xóa cho đến khi kích thước giảm xuống dưới 50% giới hạn. Việc dọn dẹp TTL diễn ra trong quá trình khởi tạo bộ nhớ đệm và mỗi lần gọi cleanExpired.

Ví dụ sử dụng Kingfisher trong Swift

Kingfisher cung cấp một số giao diện để tải hình ảnh: phần mở rộng trên UIImageView, trình quản lý riêng và SwiftUI View.

Tải trong UIImageView qua kf

kf là thuộc tính không gian tên trên UIImageView, cung cấp các phương thức setImage, cancelDownload và chỉ báo tải. Phương thức setImage chấp nhận URLSource và các tham số tùy chọn Options và 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("Đã tải \(receivedSize) / \(totalSize)")
    }
)

Phương thức trả về DownloadTask hỗ trợ hủy qua cancel và theo dõi tiến trình. Bên trong, setImage gọi KingfisherManager.shared.retrieveImage với tự động phát hiện ImageView là Target.

Sử dụng với async/await

Từ Kingfisher 7.0, phương thức setImage có sẵn ở phiên bản không đồng bộ. Điều này cho phép tích hợp tải hình ảnh vào Swift Structured Concurrency mà không cần 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 chứa UIImage
    } catch {
        print("Thất bại: \(error)")
    }
}

KFImage cho SwiftUI

KFImage là SwiftUI View, tương tự AsyncImage từ iOS 15, nhưng có hỗ trợ đầy đủ bộ nhớ đệm Kingfisher. View tự động sử dụng KingfisherManager.shared nhưng hỗ trợ trình quản lý tùy chỉnh thông qua bộ sửa đổi .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)
    }
}

Chỉ báo tải trong Kingfisher

Kingfisher cung cấp hệ thống chỉ báo tích hợp để hiển thị tiến trình tải hình ảnh. IndicatorType là kiểu liệt kê với ba tùy chọn: .activity (UIActivityIndicatorView), .progress (UIProgressView) và .custom (triển khai tùy chỉnh giao thức Indicator). Chỉ báo tự động xuất hiện trên ImageView trong khi tải và ẩn sau khi hoàn thành.

Đối với chỉ báo tùy chỉnh, cần triển khai giao thức Indicator với các phương thức startAnimatingView() và stopAnimatingView(). Điều này cho phép các giải pháp kết hợp: khung xương với hoạt ảnh shimmer, hình ảnh giữ chỗ với tiết lộ dần dần hoặc logo với hoạt ảnh độ mờ. Kingfisher cũng hỗ trợ thiết lập chỉ báo toàn cục qua KingfisherManager.shared.defaultOptions.

Kingfisher vs SDWebImage

Trên nền tảng iOS, Kingfisher và SDWebImage là hai thư viện tải hình ảnh thống trị. Sự lựa chọn giữa chúng phụ thuộc vào ngôn ngữ dự án, yêu cầu hiệu suất và hệ sinh thái.

Lợi thế chính của Kingfisher là kiến trúc Swift-first: hỗ trợ đầy đủ async/await, Combine Publishers, Sendable và kiểu Result. SDWebImage duy trì vị trí dẫn đầu nhờ hệ sinh thái plugin rộng hơn (WebP, SVG, MapKit) và hỗ trợ Objective-C.

Thiết lập Kingfisher trong dự án iOS

Kingfisher được cài đặt qua Swift Package Manager, CocoaPods hoặc Carthage. Sau khi cài đặt, chỉ cần nhập mô-đun và gọi bất kỳ phương thức tải nào — thư viện đã sẵn sàng sử dụng mà không cần cấu hình thêm.

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

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

Để tùy chỉnh cài đặt toàn cục, sử dụng KingfisherManager.shared. Bạn có thể thay đổi thời gian chờ của bộ tải, chiến lược bộ nhớ đệm và bộ xử lý mặc định. Dưới đây là ví dụ cấu hình bộ nhớ đệm 500 MB với TTL 14 ngày.

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 cũng được cấu hình qua trình quản lý: bạn có thể đặt URLSessionConfiguration tùy chỉnh với thời gian chờ, tiêu đề và chính sách bộ nhớ đệm. Để theo dõi tiến trình, mô-đun KFIndicator có sẵn với hỗ trợ ActivityIndicator, ProgressView và chỉ báo tùy chỉnh.