Kingfisher — 概要、主要概念、ImageCache

Kingfisherとは？

Kingfisherは、Appleプラットフォーム向けの非同期画像読み込みとキャッシュのためのライブラリで、完全にSwiftで書かれています。ライブラリの作者はWei Wang（onevcat）です。Kingfisherは、自動キャッシュ、変換、そしてasync/await、Combine、Sendableといった最新のSwift技術のサポートを備えた、ネットワークからの画像読み込みツールセットを提供します。

このライブラリはGitHubで23,000以上のスターを獲得しており、Telegram、Snapchat、Dropboxなどのアプリケーションで使用されています。KingfisherはGIF、APNG、HEIF、およびすべての標準画像フォーマットをサポートしています。各リクエストはタイプセーフなResultを返し、型キャストエラーを排除します。

Kingfisherのアーキテクチャは、Manager（ダウンロードマネージャー）、Cache（2レベルキャッシュ）、Processor（変換）の3つの主要コンポーネントで構成されています。これらのコンポーネントはプロトコルを介して接続されており、依存関係を変更せずに任意の部分を置き換えることができます。

Kingfisherの仕組み：ManagerとCache

KingfisherManagerは、画像の読み込み、キャッシュ、処理を調整する中心的なクラスです。ImageCacheとImageDownloaderへの参照を保持し、すべての段階を経て準備完了の画像を返す単一のメソッドretrieveImageを提供します。

読み込みプロセス

retrieveImageを呼び出すと、Managerは最初にメモリキャッシュを確認します — ソースURLとCacheSerializerからキーが形成されるUIImageのNSCacheです。画像が見つかれば即座に返されます。見つからない場合は、ディスクキャッシュを確認します — シリアライザーを介した復号化によるファイルシステムからの読み取りです。ディスクキャッシュが空の場合は、ImageDownloaderを介してネットワークリクエストが実行され、結果がデコード、変換され、両方のキャッシュレベルに保存されます。

• メモリキャッシュ — NSCacheベース、メモリ警告時に自動クリア
• ディスクキャッシュ — TTLとサイズ制限チェック付きのファイルストレージ
• ImageDownloader — モディファイアによるリクエスト変更をサポートするURLSessionベース

Swift Concurrency

バージョン7.0以降、Kingfisherはasync/awaitを完全にサポートしています。retrieveImageメソッドは非同期関数として利用可能で、完了ハンドラなしで直接Resultを返します。これにより、Structured Concurrencyを使用した最新のSwiftアーキテクチャでライブラリを使用できます。

Kingfisherの主要モジュール

Kingfisherは複数のモジュールに分割されており、各モジュールが独自のタスクを解決します。この分割により、テストとコンポーネントの交換が容易になります。

KingfisherManager

KingfisherManagerは、読み込み、キャッシュ、プロセッサを組み合わせたファサードです。デフォルトではシングルトンKingfisherManager.sharedが使用されますが、分離されたシナリオ（ユニットテストなど）用にカスタム設定の個別インスタンスを作成できます。

ImageCache

ImageCacheは、メモリとディスク用に個別の設定を持つ2レベルのキャッシュです。メモリキャッシュにはオブジェクト数の制限はありませんが、メモリ不足時にシステムによってクリアされます。ディスクキャッシュは、設定可能なTTL（デフォルト7日）、サイズ制限（デフォルト0 — 制限なし）、自動クリーンアップとともにディレクトリにファイルを保存します。

ImageProcessor

ImageProcessorは、処理済み画像を返す単一のメソッドprocess(item:options:)を持つプロトコルです。組み込み実装：ResizingImageProcessor（サイズ変更）、RoundCornerImageProcessor（角丸）、BlurImageProcessor（ガウシアンブラー）、OverlayImageProcessor（カラーオーバーレイ）。プロセッサは|>演算子を使用して組み合わせることができます。

Kingfisherのキャッシュシステム

Kingfisherのキャッシュアーキテクチャはwrite-through原則に基づいています：データは両方のレベルに同時に書き込まれ、読み取りは最も高速なレベルであるメモリから開始されます。キャッシュキーは、クエリパラメータを除去した後の絶対画像URLです。

ディスクキャッシュのサイズを管理するには、最終アクセス日でソートしてファイルの合計サイズを計算します。制限を超えた場合、サイズが制限の50%を下回るまで、最も古いアクセス日のファイルが削除されます。TTLクリーンアップは、キャッシュの初期化時とcleanExpiredの呼び出し時に行われます。

SwiftでのKingfisher使用例

Kingfisherは画像読み込みのためのいくつかのインターフェースを提供します：UIImageViewの拡張、個別のマネージャー、SwiftUI View。

kfを使用したUIImageViewでの読み込み

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)")
    }
)

このメソッドは、cancelによるキャンセルと進行状況の追跡をサポートするDownloadTaskを返します。内部的には、setImageはImageViewをTargetとして自動検出し、KingfisherManager.shared.retrieveImageを呼び出します。

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("失敗: \(error)")
    }
}

SwiftUI用KFImage

KFImageは、iOS 15のAsyncImageと似ていますが、Kingfisherの完全なキャッシュサポートを備えたSwiftUI Viewです。この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は3つのオプションを持つ列挙型です：.activity（UIActivityIndicatorView）、.progress（UIProgressView）、.custom（Indicatorプロトコルのカスタム実装）。インジケータは読み込み中にImageViewの上に自動的に表示され、完了後に非表示になります。

カスタムインジケータの場合は、startAnimatingView()およびstopAnimatingView()メソッドを持つIndicatorプロトコルを実装する必要があります。これにより、シャイマーアニメーション付きスケルトン、段階的に表示されるプレースホルダー画像、透明度アニメーション付きロゴなどのハイブリッドソリューションが可能になります。KingfisherはKingfisherManager.shared.defaultOptionsを介してグローバルにインジケータを設定することもサポートしています。

Kingfisher vs SDWebImage

iOSプラットフォームでは、KingfisherとSDWebImageが2大画像読み込みライブラリです。どちらを選ぶかは、プロジェクトの言語、パフォーマンス要件、エコシステムによって異なります。

Kingfisherの主な利点は、Swift-firstアーキテクチャです：async/await、Combine Publishers、Sendable、Result型の完全サポート。SDWebImageは、より広範なプラグインエコシステム（WebP、SVG、MapKit）とObjective-Cサポートによりリーダーシップを維持しています。

iOSプロジェクトでのKingfisher設定

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を使用します。ダウンローダーのタイムアウト、キャッシュ戦略、デフォルトのプロセッサを変更できます。以下は、14日間のTTLで500 MBのキャッシュを設定する例です。

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を設定できます。進行状況の監視には、ActivityIndicator、ProgressView、カスタムインジケータをサポートするKFIndicatorモジュールが利用可能です。