Swift - Kingfisher

이번 글에서는 이미지 관련 오픈소스 라이브러리인 Kingfisher에 대해 알아볼게요

Kingfisher

Kingfisher는 iOS에서 원격 이미지를 쉽게 다루게 해주는 오픈소스 라이브러리로 핵심은 3가지예요

• 이미지 다운로드
• 캐시(메모리/디스크)
• 이미지 처리(다운샘플링, 리사이즈 등)

SwiftUI에서는 KFImage로 바로 쓸 수 있어서 화면 코드가 꽤 간결해집니다

장점

• 캐시가 강력함
  메모리/디스크 캐시가 있어서 같은 이미지 재요청 비용이 줄어들어요
• 성능 튜닝이 쉬움
  큰 이미지에서 Downsampling 옵션으로 메모리 급증을 줄일 수 있어요
• 실패 대응이 쉬움
  placeholder, retry, fallback 이미지 처리 등이 간단합니다
• 코드가 짧아짐
  직접 구현하면 ViewModel/캐시/스토리지/취소 처리까지 코드가 길어지는데, Kingfisher는 화면에서 선언적으로 처리 가능합니다

사용법

다음은 kingfisher의 기능별 사용 방법입니다

로딩 placeholder

KFImage(url)
    .placeholder { ProgressView() }

실패 콜백

KFImage(url)
    .onFailure { error in
        print(error)
    }

실패했을 때 이미지는 바로 보여주지 못해서 콜백함수에서 상태를 관리해 보여줘야합니다.

struct ExampleView: some View {
	@State var isLoadFailed: Bool = false
    
    var body: some View {
    	if loadFailed {
                VStack {
                    Image("fallback")
                        .resizable()
                        .scaledToFill()
                }
        } else {
        	KFImage.url(URL(string: imageURL))
            	.onFailure { _ in
                	loadFailed = true
                }
                .placeholder {
                    ProgressView()
                }
                .resizable()
                .scaledToFill()
            }
        }
    }
}

성공 콜백

KFImage(url)
    .onSuccess { result in
        print(result.cacheType)
    }

자동 재시도

KFImage(url)
    .retry(maxCount: 2, interval: .seconds(1))

다운샘플링(대용량 이미지 성능)

KFImage(url)
    .setProcessor(DownsamplingImageProcessor(size: CGSize(width: 300, height: 300)))
    .scaleFactor(UIScreen.main.scale)

프로세서 체인(예: 리사이즈 + 라운드코너)

KFImage(url)
    .setProcessor(
        ResizingImageProcessor(referenceSize: CGSize(width: 300, height: 300))
        |> RoundCornerImageProcessor(cornerRadius: 16)
    )

원본 이미지 캐시

KFImage(url)
    .cacheOriginalImage()

디스크/메모리 캐시 만료 설정

KFImage(url)
    .diskCacheExpiration(.days(7))
    .memoryCacheExpiration(.seconds(300))

뷰 사라질 때 다운로드 취소

KFImage(url)
    .cancelOnDisappear(true)

강제 새로고침(캐시 무시)

KFImage(url)
    .forceRefresh(true)

로드 전 페이드 트랜지션

KFImage(url)
    .fade(duration: 0.2)

요청 타임아웃 설정

KFImage(url)
    .requestModifier(AnyModifier { request in
        var r = request
        r.timeoutInterval = 10
        return r
    })

헤더 추가(예: Authorization)

KFImage(url)
    .requestModifier(AnyModifier { request in
        var r = request
        r.setValue("Bearer <token>", forHTTPHeaderField: "Authorization")
        return r
    })

특정 캐시 키 지정

KFImage(url)
    .cacheMemoryOnly()
    .cacheOriginalImage()

메모리 전용 캐시

KFImage(url)
    .cacheMemoryOnly()

로딩 우선순위 조정

KFImage(url)
    .loadDiskFileSynchronously()
    .backgroundDecode()

렌더링용 SwiftUI 조합

KFImage(url)
    .resizable()
    .scaledToFill()
    .clipped()

prefetch (리스트 진입 전 미리 로드)

let urls: [URL] = [
    URL(string: "https://example.com/1.jpg")!,
    URL(string: "https://example.com/2.jpg")!
]
let prefetcher = ImagePrefetcher(urls: urls)
prefetcher.start()

캐시 삭제

ImageCache.default.clearMemoryCache()
ImageCache.default.clearDiskCache()