Coil 源码分析

一、整体架构概览

Coil是 2018 年发布的 Kotlin 协程原生图片库。整体设计借鉴 OkHttp 的拦截器模式，全程协程驱动。

主要组件

ImageLoader // 图片加载器，全局单例，管理所有请求
ImageRequest // 单次请求的配置对象
RequestDelegate // 生命周期管理，绑定 View/Lifecycle
InterceptorChain // 拦截器链。串联所有处理环节
Fetcher // 数据获取
Decoder // 图片解码

二、完整加载流程

imageView.load
→ imageLoader.enqueue // 启动协程
→ executeMain // 主线程初始化
→ requestDelegate.start // 绑定生命周期
→ 拦截器链 proceed
MemoryCacheInterceptor // 查内存缓存
DiskCacheInterceptor // 查磁盘缓存
FetcherInterceptor // 网络请求
DecoderInterceptor // 图片解码
→ target.onSuccess // 主线程显示

使用者痛点：图片加载卡顿或闪烁时很难判断是缓存未命中还是网络慢，需要定位到具体拦截器。

三、拦截器链设计

接口对比

// OkHttp 拦截器
interface Interceptor {
fun intercept: Response
interface Chain {
fun request: Request
fun proceed: Response
}
}
// Coil 拦截器
interface Interceptor {
suspend fun intercept: ImageResult
interface Chain {
val request: ImageRequest
suspend fun proceed: ImageResult
}
}

内置拦截器列表

使用者自定义 Interceptor
→ EngineInterceptor // 引擎。负责调度
→ MemoryCacheInterceptor // 查内存缓存
→ DiskCacheInterceptor // 查磁盘缓存
→ FetcherInterceptor // 获取原始数据
→ DecoderInterceptor // 解码图片

拦截器链执行原理

// RealInterceptorChain.kt
override suspend fun proceed: ImageResult {
val interceptor = interceptors
val next = copy // 指向下一个
return interceptor.intercept // 传入 next，拦截器调 next.proceed 继续链
}

执行方法的观点是，

proceed
→ MemoryCache.intercept
→ chain.proceed
→ DiskCache.intercept
→ chain.proceed
→ Fetcher.intercept
→ chain.proceed
→ Decoder.intercept
→ 返回结果
← Decoder 写缓存
← Fetcher 返回
← DiskCache 写磁盘
← MemoryCache 写内存

使用者痛点：自定义拦截器时常忘记调用 chain.proceed 导致请求中断。

四、协程在各环节的运用

enqueue 启动协程

override fun enqueue: Disposable {
val job = imageLoaderScope.launch {
val result = executeMain
when {
is SuccessResult -> target.onSuccess)
is ErrorResult -> target.onError)
}
}
return CoroutineDisposable // 封装 Job，支持 dispose 取消
}

executeMain 线程切换

private suspend fun executeMain: ImageResult =
withContext { // 确保主线程
val requestDelegate = requestService.requestDelegate(
request = initialRequest。job = coroutineContext.job // 把当前协程 Job 传给 delegate
)
requestDelegate.start // 注册生命周期监听
withContext { // 切到 IO 线程
RealInterceptorChain.proceed
}
}

HttpUriFetcher — 回调桥接成挂起函数

override suspend fun fetch: FetchResult {
val call = okHttpClient.newCall
val response = suspendCancellableCoroutine { continuation ->
// 协程取消 → 自动取消 OkHttp 请求
continuation.invokeOnCancellation { call.cancel }
call.enqueue(object : Callback {
override fun onResponse {
continuation.resume // 恢复协程，返回结果
}
override fun onFailure {
continuation.resumeWithException // 恢复协程，抛异常
}
})
}
return SourceResult(
source = response.body!，.source.toImageSource,...
)
}

DecoderInterceptor 线程切换

override suspend fun intercept: ImageResult {
val bitmap = withContext {
decoder.decode // CPU 密集，切到 Default 线程池
}
val transformed = withContext {
request.transformations.fold { b,t -> t.transform }
}
return SuccessResult。...)
}

线程流转总图

主线程 imageView.load
└── imageLoaderScope.launch
│
└── withContext
← executeMain
├── requestDelegate.start
├── target.onStart
│
└── withContext
← 拦截器链
├── MemoryCache
├── DiskCache
├── Fetcher
│ └── suspendCancellableCoroutine
│ OkHttp enqueue → continuation.resume
└── Decoder
└── withContext
← 结果回到 Main
target.onSuccess

使用者痛点：在低端设备上出现 UI 卡顿，多数情况下是 Decoder 没有切到 Default 导致主线程阻塞。

五、生命周期管理

imageLoaderScope 的作用域与结构化并发

private val imageLoaderScope = CoroutineScope(
SupervisorJob + // 子请求失败互不影响
Dispatchers.Main.immediate +
CoroutineExceptionHandler { ... })

该 Scope 的生命周期等同于 ImageLoader 实例，需要手动调用 .shutdown 才会真正释放资源。

requestDelegate 两种实现细节对比

BaseRequestDelegate

internal class BaseRequestDelegate(
private val lifecycle: Lifecycle,private val job: Job,) : RequestDelegate,DefaultLifecycleObserver {
override fun start { lifecycle.addObserver }
override fun onDestroy {
finish
job.cancel // onDestroy 时取消，不再重启
}
}

ViewTargetRequestDelegate

internal class ViewTargetRequestDelegate(
private val imageLoader: ImageLoader,private val initialRequest: ImageRequest,private val target: ViewTarget<*>,private val lifecycle: Lifecycle。private val job: Job,) : RequestDelegate,DefaultLifecycleObserver,View.OnAttachStateChangeListener {
override fun start {
target.view.addOnAttachStateChangeListener // View维度监听
lifecycle.addObserver // Lifecycle维度监听
}
// ── View 生命周期 ──────────────────────
override fun onViewDetachedFromWindow { job.cancel } // RecyclerView 滑走时取消
override fun onViewAttachedToWindow { imageLoader.enqueue }
// ── Lifecycle 生命周期 ──────────────────────
override fun onStop { job.cancel } // 切后台取消
override fun onStart{ imageLoader.enqueue }
override fun onDestroy{
finish
job.cancel
}
}

使用者痛点：RecyclerView 中快速滑动导致大量请求未及时取消，引起 OOM；通过上述两种 Delegate 可以确保在视图离屏或页面销毁时自动 cancel。

取消入口汇总与传播链路

• `disposable.dispose` – 调用方主动取消。
• `imageView.load` – 新请求替换旧请求。
• `onViewDetachedFromWindow` – RecyclerView 滑走时自动 cancel。按理说，
• `lifecycle.onStop` – 页面进入后台时 cancel。
• `lifecycle.onDestroy` – 页面销毁时 cancel。
• `imageLoader.shutdown` – 整个 ImageLoader 实例关闭。

取消传播示意这方面，

→ job.cancel
→ 中止 executeMain 协程及其子协程
→ 若处于 suspendCancellableCoroutine 挂起状态。则 invokeOnCancellation 调用 OkHttpCall.cancel
→ 若处于 withContext…解码阶段，则收到 CancellationException 并立即停止解码
→ 所有资源统一释放，无内存泄漏风险
codе​/prе​​

六、缓存设计详解

<="" p="">

级别	实现	存储内容	命中后行为
内存缓存	WeakReference + LruCache	已解码 Bitmap / Drawable	直接返回。可立即渲染
磁盘缓存	OkHttp DiskCache	压缩后的原始数据流	读取后交由 Decoder 再解码

。

---