CacheControl 与缓存指令：max‑age、no‑cache、no‑store、only‑if‑cached

1. 概念与原理

HTTP Cache-Control 头部是客户端与服务器协商缓存行为的核心机制。OkHttp 通过 CacheControl 类封装这些指令，开发者可以精确控制请求应如何使用缓存，以及响应应如何被缓存。指令分为两大类：请求指令（客户端发往服务器，影响中间缓存和源站的处理方式）与 响应指令（服务器返回给客户端，限定本地缓存策略）。本章重点介绍四个最常用的指令：max‑age、no‑cache、no‑store、only‑if‑cached。

2. 流程图：指令如何影响缓存决策

下图展示请求携带不同 Cache-Control 指令时，OkHttp 缓存拦截器的核心判断分支。注意 only-if-cached 会跳过网络请求，no-cache 会导致即使有缓存也要重新验证。

3. OkHttp 中的 CacheControl API

OkHttp 提供 CacheControl.Builder 来构建指令，通过 Request.Builder.cacheControl() 或 Response.cacheControl() 应用。以下示例展示常用指令组合：

// 构建请求：max-age=60，且只接受缓存（only-if-cached）
val cacheControl = CacheControl.Builder()
    .maxAge(60, TimeUnit.SECONDS)
    .onlyIfCached()
    .build()

val request = Request.Builder()
    .url("https://api.example.com/data")
    .cacheControl(cacheControl)
    .build()

// 响应端检查指令
val response = client.newCall(request).execute()
val responseCC = response.cacheControl()
println("max-age = ${responseCC.maxAgeSeconds}")       // 或 -1 表示未设置
println("no-cache = ${responseCC.noCache}")            // true/false
println("no-store = ${responseCC.noStore}")            // true/false
println("only-if-cached = ${responseCC.onlyIfCached}") // 仅在请求有效

4. 实现流程：在缓存拦截器中注入自定义 CacheControl

通过自定义 Interceptor，可以在运行时动态添加或修改 CacheControl 指令。典型场景：根据网络状态（WiFi/移动数据/离线）切换缓存策略。

1. 创建拦截器，实现 Interceptor 接口。
2. 在 intercept() 方法中获取原始 Request。
3. 构造新的 CacheControl，合并业务逻辑（例如：当前为弱网络时增加 max‑age，检测到离线强制 only‑if‑cached）。
4. 使用 request.newBuilder().cacheControl(newCC).build() 替换请求。
5. 调用 chain.proceed(newRequest) 获取响应。
6. 可选：根据响应状态或业务需求修改响应端缓存指令（例如替换 Cache-Control 响应头）。

class DynamicCacheInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val originalRequest = chain.request()

        // 假设当前网络为离线状态
        val isOffline = true
        val newCacheControl = if (isOffline) {
            CacheControl.Builder()
                .onlyIfCached()
                .maxAge(Int.MAX_VALUE, TimeUnit.SECONDS) // 允许使用任何过期的缓存
                .build()
        } else {
            CacheControl.Builder()
                .maxAge(30, TimeUnit.SECONDS)
                .build()
        }

        val modifiedRequest = originalRequest.newBuilder()
            .cacheControl(newCacheControl)
            .build()

        val response = chain.proceed(modifiedRequest)
        // 若想在响应端强制 no-cache，可修改响应头（需使用 Response.Builder）
        return response
    }
}

5. 调试与验证

• 日志拦截器：使用 HttpLoggingInterceptor 输出完整的请求/响应头，查看 Cache-Control 是否按预期发送。
• OkHttp 事件监听器：通过 EventListener 的 cacheHit()/cacheMiss() 事件判断缓存决策是否正确。
• 抓包工具：使用 Charles 或 Wireshark 抓取 HTTP 报文，验证 Cache-Control 指令的头部值。

// 日志拦截器示例
val logger = HttpLoggingInterceptor { message -> Log.d("OKHTTP", message) }
logger.setLevel(HttpLoggingInterceptor.Level.HEADERS)

val client = OkHttpClient.Builder()
    .addInterceptor(logger)
    .cache(Cache(File(cacheDir, "http_cache"), 5L * 1024 * 1024))
    .addInterceptor(DynamicCacheInterceptor())
    .build()

6. 常见错误与陷阱

7. 性能与稳定性优化

• 合理设定 max‑age：对于不常变动的静态资源（图标、CSS），设置较长值（如 86400 秒）可大幅减少带宽消耗与延迟。
• 离线降级：监听网络变化，在断网时启用 only-if-cached + max-stale(Int.MAX_VALUE)，让应用仍然可用。
• 动态切换策略：根据用户行为（如滑动列表）区分即时数据与背景数据；即时数据使用 no-cache，背景数据使用 max-age。
• 避免过度使用 no-store：每次请求都走网络会增加服务器压力和网络延迟，仅在敏感信息（如、支付表单）中使用。