Kingfisher — 정의, 핵심 개념 및 ImageCache

Kingfisher란?

Kingfisher는 Apple 플랫폼에서 비동기 이미지 로딩 및 캐싱을 위한 라이브러리로, 완전히 Swift로 작성되었습니다. 라이브러리의 저자는 Wei Wang(onevcat)입니다. Kingfisher는 자동 캐싱, 변환 및 최신 Swift 기술(async/await, Combine, Sendable) 지원을 갖춘 네트워크 이미지 로딩 도구 세트를 제공합니다.

이 라이브러리는 GitHub에서 23,000개 이상의 별을 받았으며 Telegram, Snapchat 및 Dropbox와 같은 애플리케이션에서 사용됩니다. Kingfisher는 GIF, APNG, HEIF 및 모든 표준 이미지 형식을 지원합니다. 각 요청은 타입 안전한 Result를 반환하여 타입 캐스팅 오류를 제거합니다.

Kingfisher의 아키텍처는 Manager(다운로드 관리자), Cache(2단계 캐시) 및 Processor(변환)의 세 가지 주요 구성 요소로 구축됩니다. 이러한 구성 요소는 프로토콜을 통해 연결되어 종속성을 변경하지 않고도 모든 부분을 교체할 수 있습니다.

Kingfisher 작동 방식: Manager와 Cache

KingfisherManager는 이미지 로딩, 캐싱 및 처리를 조정하는 중앙 클래스입니다. ImageCache 및 ImageDownloader에 대한 참조를 포함하며 모든 단계를 거친 후 준비된 이미지를 반환하는 단일 메서드 retrieveImage를 제공합니다.

로딩 프로세스

retrieveImage를 호출하면 Manager는 먼저 메모리 캐시를 확인합니다 — 소스 URL과 CacheSerializer로 키가 형성되는 UIImage의 NSCache입니다. 이미지를 찾으면 즉시 반환됩니다. 찾지 못하면 디스크 캐시를 확인합니다 — serializer를 통한 복호화로 파일 시스템에서 읽습니다. 디스크 캐시가 비어 있으면 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은 세 가지 옵션이 있는 열거형입니다: .activity (UIActivityIndicatorView), .progress (UIProgressView) 및 .custom (Indicator 프로토콜의 사용자 정의 구현). 인디케이터는 로딩 중에 ImageView 위에 자동으로 표시되고 완료 후 숨겨집니다.

사용자 정의 인디케이터의 경우 startAnimatingView() 및 stopAnimatingView() 메서드로 Indicator 프로토콜을 구현해야 합니다. 이를 통해 샤이머 애니메이션이 있는 스켈레톤, 점진적 표시가 있는 플레이스홀더 이미지 또는 투명도 애니메이션이 있는 로고와 같은 하이브리드 솔루션이 가능합니다. 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 지원으로 리더십을 유지하고 있습니다.

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로 500MB 캐시를 구성하는 예제입니다.

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 모듈을 사용할 수 있습니다.