4. 基于拦截器的离线缓存实现：Interceptor原理、网络拦截器与应用拦截器区别

4.1 Interceptor 原理概述

Retrofit 的底层网络通信由 OkHttp 完成，而 OkHttp 的核心扩展机制就是拦截器链（Interceptor Chain）。每一个网络请求在发出前和响应返回后，都会依次经过一组注册好的拦截器，形成一个类似“洋葱”的嵌套调用模型。

• 责任链模式：每个拦截器都可以对 Request 进行预处理，然后调用 chain.proceed() 将请求传给下一个拦截器，最后拿到 Response 进行后处理。
• 分层处理：拦截器链允许开发者在不修改 OkHttp 核心代码的前提下，插入自定义逻辑——缓存、重试、日志、Header 注入等。
• 离线缓存切入点：利用拦截器对 Request/Response 的拦截能力，可以在无网络时直接返回本地缓存，避免请求失败。

4.2 网络拦截器 vs 应用拦截器

OkHttp 提供两种注册拦截器的方式：addInterceptor()（应用拦截器）和 addNetworkInterceptor()（网络拦截器）。它们在执行时机、触发次数和可见范围上存在本质差异。

4.3 离线缓存拦截器设计思路

离线缓存的核心是利用应用拦截器在请求链最外层的特性，在网络不可用时直接返回已存储的缓存响应，避免请求穿透到网络层导致失败。

1. 检测网络状态：在 intercept() 方法中通过 ConnectivityManager 判断当前是否联网。
2. 有网络：正常放行请求，同时通过 Cache-Control 头控制缓存有效期（如 max-age=60）。
3. 无网络：修改请求头为 only-if-cached，强制 OkHttp 仅从缓存返回；若缓存不存在则返回自定义兜底响应（如 503 + 错误标识）。
4. 缓存写入：依赖 OkHttp 自带的 Cache 对象自动管理磁盘缓存，无需手动序列化。

4.4 核心代码实现

下面是一个完整的离线缓存拦截器实现，包含网络检测、缓存策略注入和兜底响应。

// OfflineCacheInterceptor.kt
class OfflineCacheInterceptor(
    private val context: Context,
    private val maxAgeSeconds: Int = 60          // 在线缓存有效期
) : Interceptor {

    override fun intercept(chain: Interceptor.Chain): Response {
        val originalRequest = chain.request()
        
        // 1. 检测网络状态
        val isOnline = isNetworkAvailable()
        
        return if (!isOnline) {
            // 2. 无网络 → 仅从缓存返回
            val cacheRequest = originalRequest.newBuilder()
                .header("Cache-Control", "only-if-cached")
                .removeHeader("Pragma")
                .build()
            
            try {
                chain.proceed(cacheRequest)
            } catch (e: Exception) {
                // 3. 缓存不存在时返回兜底响应
                Response.Builder()
                    .code(503)
                    .message("Offline: No cache available")
                    .protocol(Protocol.HTTP_1_1)
                    .request(originalRequest)
                    .body(ResponseBody.create(
                        MediaType.parse("text/plain"),
                        "{\"error\":\"offline\",\"message\":\"无网络且无缓存\"}"
                    ))
                    .build()
            }
        } else {
            // 4. 有网络 → 正常请求 + 设置缓存有效期
            val networkRequest = originalRequest.newBuilder()
                .header("Cache-Control", "max-age=$maxAgeSeconds")
                .removeHeader("Pragma")
                .build()
            
            chain.proceed(networkRequest)
        }
    }

    private fun isNetworkAvailable(): Boolean {
        val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
        val network = cm.activeNetwork ?: return false
        val caps = cm.getNetworkCapabilities(network) ?: return false
        return caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
    }
}

在 OkHttpClient 中注册并启用 Cache：

// OkHttpClient 配置
val cacheDir = File(context.cacheDir, "http_cache")
val httpCache = Cache(cacheDir, 10L * 1024 * 1024)  // 10MB 磁盘缓存

val okHttpClient = OkHttpClient.Builder()
    .cache(httpCache)                                    // 启用 OkHttp 缓存
    .addInterceptor(OfflineCacheInterceptor(context))    // 离线缓存拦截器（第一个添加）
    .addInterceptor(HttpLoggingInterceptor().apply {    // 日志拦截器（调试用）
        level = HttpLoggingInterceptor.Level.BODY
    })
    .addNetworkInterceptor(NetworkMonitorInterceptor()) // 网络监控拦截器
    .build()

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .client(okHttpClient)
    .addConverterFactory(GsonConverterFactory.create())
    .build()

4.5 调试与验证

离线缓存拦截器的调试核心是验证“有网络时缓存是否写入”和“无网络时是否回退缓存”。

• 日志输出：在拦截器中增加日志标记，区分“在线模式”和“离线模式”。
• 断点调试：在 intercept() 方法的 isNetworkAvailable 分支处设置断点，观察 Cache-Control 头是否正确注入。
• 网络模拟：使用 Android 模拟器的“飞行模式”或 Charles 的“断网”功能模拟离线场景。

4.6 常见错误与避坑

4.7 性能与稳定性优化

• 缓存大小控制：根据 API 数据量合理设置 Cache 的 maxSize，避免耗尽磁盘空间。建议值：图片类 50MB，纯 JSON 数据 10MB。
• 缓存淘汰策略：OkHttp 内部使用 LRU（最近最少使用）算法自动淘汰缓存，无需手动干预。但应避免在短时间内生成大量不同 URL 的请求，防止缓存污染。
• 并发安全：OkHttp 的 Cache 是线程安全的，多个请求同时读写缓存不会出现数据竞争。但自定义的 isNetworkAvailable() 应避免在 UI 线程频繁调用。
• 缓存一致性：对于时效性敏感的数据（如用户余额），可在有网络时设置较短的 max-age（如 15 秒），离线时再使用缓存兜底。
• 响应体复用：缓存的 Response Body 只能读取一次，如果多个拦截器需要读取 Body，必须使用 PeekSource 或 Buffer 复制，避免流关闭。