2. Cache-Control 指令详解：max-age、s-maxage、no-cache、no-store、must-revalidate

2.1 指令原理与缓存决策模型

Cache-Control 是 HTTP/1.1 中定义的缓存控制头部，它通过一组指令（directives）告诉客户端、代理服务器以及中间缓存如何处理响应和请求。在 OkHttp 磁盘缓存中，这些指令直接决定了缓存能否被存储、能否被复用以及何时需要向服务器验证。

下表总结了本节五个关键指令的语义和作用范围：

2.2 指令优先级与组合规则

当多个指令同时出现时，OkHttp 按照以下优先级解析：

1. no-store > 一切：直接跳过缓存。
2. no-cache > max-age：即使 max-age 很大，也要强制重新验证。
3. s-maxage 仅在共享缓存中覆盖 max-age，OkHttp 忽略。
4. must-revalidate 仅在缓存过期后生效：若缓存未过期，资源可直接使用。

2.3 流程图：Cache-Control 缓存决策路径

下面的 SVG 图展示了 OkHttp 收到响应时，根据 Cache-Control 指令决定是否缓存以及缓存使用流程：

2.4 配置实战：OkHttp 如何使用 Cache-Control

OkHttp 的 Cache 模块内置了完整的 HTTP 缓存协定支持。以下是三种典型配置场景：

2.4.1 服务端响应头示例（后端需设置）

// 示例1：私有缓存，1小时新鲜期
Cache-Control: private, max-age=3600

// 示例2：禁止缓存（如登录API）
Cache-Control: no-store

// 示例3：强制每次验证，但允许有条件使用缓存
Cache-Control: no-cache, must-revalidate

// 示例4：共享缓存优先，私有缓存使用备选时长
Cache-Control: public, s-maxage=600, max-age=300

2.4.2 OkHttp 客户端代码：设置缓存大小并生效

// 创建缓存目录和 Cache 对象
File cacheDir = new File(context.getCacheDir(), "http_cache");
int cacheSize = 10 * 1024 * 1024; // 10 MB
Cache cache = new Cache(cacheDir, cacheSize);

// 配置 OkHttpClient
OkHttpClient client = new OkHttpClient.Builder()
    .cache(cache)
    .build();

// 请求时自动处理 Cache-Control, 无需额外配置
Request request = new Request.Builder()
    .url("https://api.example.com/profile")
    .build();

Response response = client.newCall(request).execute();
// 如果服务端返回 Cache-Control: max-age=3600
// 则后续1小时内同URL请求直接返回缓存，不会触发网络

2.4.3 强制刷新缓存（客户端覆盖服务端指令）

某些场景需要客户端主动忽略缓存（例如用户下拉刷新），可通过请求头覆盖：

Request refreshRequest = new Request.Builder()
    .url("https://api.example.com/profile")
    .header("Cache-Control", "no-cache")   // 告诉代理/服务端不用缓存响应
    .build();

2.5 常见错误与性能陷阱

2.6 稳定性与调试建议

• 启用 OkHttp 日志拦截器：观察每次请求是 命中缓存 还是 网络请求。

  HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
  logging.setLevel(HttpLoggingInterceptor.Level.HEADERS);
  client = client.newBuilder()
      .addInterceptor(logging)
      .build();

• 使用 CacheControl.FORCE_NETWORK 和 FORCE_CACHE：在测试阶段强制验证缓存策略是否符合预期。

  Request forceNetworkRequest = request.newBuilder()
      .cacheControl(CacheControl.FORCE_NETWORK)
      .build();
  Response response = client.newCall(forceNetworkRequest).execute();

• 检查磁盘缓存目录：Android 中 getCacheDir()/http_cache 下会生成 journal 和 .0/.1 文件，文件大小反映缓存使用量。

2.7 总结

• max-age 控制新鲜度，是日常最常用的指令。
• s-maxage 专用于 CDN/代理，客户端不需要处理。
• no-cache 强制验证，适合频繁变动的资源。
• no-store 完全禁止缓存，适合安全敏感或一次性数据。
• must-revalidate 配合 max-age 使用，确保过期后一定验证。