1. OkHttp 缓存核心组件解析

本章深入剖析 OkHttp 离线缓存体系的四个基础构件：Cache 类、CacheStrategy、DiskLruCache 与拦截器链。理解这些组件的职责与协作方式是掌握离线缓存同步策略的前置条件。

1.1 架构概览

下图展示了缓存组件在 OkHttp 请求链路中的位置与关系：

1.2 Cache 类

Cache 是 OkHttp 暴露给开发者的高层缓存接口，位于 okhttp3.Cache。它封装了 DiskLruCache 并提供缓存写入、读取、驱逐、大小监控等能力。

File cacheDir = new File(context.getCacheDir(), "http_cache");
int cacheSize = 10 * 1024 * 1024; // 10MB
Cache cache = new Cache(cacheDir, cacheSize);
OkHttpClient client = new OkHttpClient.Builder()
        .cache(cache)
        .build();

1.3 CacheStrategy 缓存策略

CacheStrategy 是 OkHttp 缓存决策的核心计算单元。它接收一个原始的 Request 和缓存的 Response（如果存在），输出一个 CacheStrategy 对象，其中包含两个字段：

• networkRequest：如果为 null，则直接返回缓存；否则发起网络请求。
• cacheResponse：如果为 null，则不可使用缓存；否则使用此缓存响应。

决策依据主要来自 HTTP 缓存头：

1.4 DiskLruCache 源码分析

DiskLruCache 是 OkHttp 缓存组件的底层存储实现，基于 LRU（Least Recently Used）驱逐算法。核心源码位于 okhttp3.internal.cache.DiskLruCache。其主要特性：

• Journal 文件：记录每次读取、写入、删除操作，用于重启后重建 LRU 顺序。
• 条目（Entry）：每个缓存 URL 对应一个条目，每个条目包含最多 2 个快照（Clean / Dirty）。
• 容量控制：当总大小超出 maxSize 时，触发 trimToSize() 驱逐最旧条目。
• 原子性：写入通过临时文件 + 重命名保证原子性；读操作通过 Snapshot 提供一致性视图。

Journal 文件每行格式示例：

DIRTY 1be32b1f5d5a5a5e
READ 1be32b1f5d5a5a5e
CLEAN 1be32b1f5d5a5a5e 128 256
REMOVE 1be32b1f5d5a5a5e

其中 DIRTY 表示正在写入，CLEAN 后跟文件大小（两个数字分别对应索引 0 和 1 的文件大小），REMOVE 表示删除。

1.5 拦截器链中的缓存拦截器

OkHttp 默认在内部添加了 CacheInterceptor，位于拦截器链的末尾（在网络拦截器之后）。其处理流程如下：

1. 获取缓存响应：调用 Cache.get(request)。
2. 创建 CacheStrategy：传入原始请求与缓存响应。
3. 决策分支：
   • 若 networkRequest == null 且 cacheResponse != null → 直接返回缓存（离线命中）。
   • 若 networkRequest != null 且 cacheResponse == null → 发起网络请求，并将响应缓存。
   • 若两者都非空 → 发起条件请求（带 If-None-Match / If-Modified-Since），若服务返回 304 则更新缓存并返回；否则替换缓存并返回新响应。
   • 若两者均为空 → 返回 504 Gateway Timeout（未缓存且网络不允许？实际会走网络请求，仅当 only-if-cached 时返回 504）。
4. 缓存写入：将由网络获取的有效响应通过 Cache.put(response) 写入。
5. 响应处理：移除不必要的 Content-Length 等头，保持与原始响应一致。

自定义拦截器可以放在 CacheInterceptor 之前或之后以影响缓存行为。例如在应用拦截器中强制添加 Cache-Control: only-if-cached 实现离线优先。

OkHttpClient client = new OkHttpClient.Builder()
        .addInterceptor(chain -> {
            System.out.println("应用拦截器: " + chain.request().url());
            return chain.proceed(chain.request());
        })
        .addNetworkInterceptor(chain -> {
            System.out.println("网络拦截器: " + chain.request().url());
            return chain.proceed(chain.request());
        })
        .cache(new Cache(new File("cache"), 1024 * 1024))
        .build();

// 执行一次请求，观察输出顺序:
// 应用拦截器 → 网络拦截器 → CacheInterceptor（内部）

1.6 常见问题与调优