如何配置Apache HTTP Client使磁盘缓存重启后仍可读取？

问题描述 #

使用org.apache.http.impl.client.cache.CachingHttpClients构建器配置持久化HTTP缓存，通过setCacheDir指定缓存目录后，重启应用无法从磁盘读取缓存。

配置代码：

CachingHttpClients.custom()
  .setCacheDir(cacheDir)
  .setDeleteCache(false)
  .build();

观察到的现象 #

• 请求后缓存目录生成类似1703170640727.0000000000000001-997b0365.User.-url-path的缓存条目；
• 同一进程内重复请求同一URL能命中缓存；
• 重启应用后，再次请求同一URL出现缓存未命中。

最小复现代码 #

File cacheDir = Path.of(System.getProperty("java.io.tmpdir")).resolve("my-http-cache").toFile();
if (!cacheDir.exists() && !cacheDir.mkdirs()) {
  throw new RuntimeException("Could not create cache directory " + cacheDir + ".");
}
try (var client = CachingHttpClients.custom()
  .setCacheDir(cacheDir)
  .setDeleteCache(false)
  .useSystemProperties()
  .build()) {
  HttpCacheContext context = HttpCacheContext.create();
  CloseableHttpResponse response = client.execute(new HttpGet("https://api.github.com/repos/finos/common-domain-model"), context);

  CacheResponseStatus responseStatus = context.getCacheResponseStatus();
  switch (responseStatus) {
    case CACHE_HIT:
      System.out.println("Cache hit!");
      break;
    case CACHE_MODULE_RESPONSE:
      System.out.println("The response was generated directly by the caching module");
      break;
    case CACHE_MISS:
      System.out.println("Cache miss!");
      break;
    case VALIDATED:
      System.out.println("Cache hit after validation");
      break;
  }
}

问题原因与解决步骤 #

核心原因 #

Apache HttpClient默认磁盘缓存实现（FileCache）重启后无法复用缓存，是因为默认配置未启用缓存条目持久化的完整逻辑，同时缓存有效性判断严格遵循响应头规则，导致重启后缓存被判定为无效。

解决方法 #

通过调整CacheConfig参数并显式配置持久化存储实现，确保缓存条目在重启后被正确加载：

1. 配置自定义CacheConfig
   覆盖默认缓存规则，启用启发式缓存以处理无明确缓存头的响应：

   CacheConfig cacheConfig = CacheConfig.custom()
       .setMaxCacheEntries(1000) // 最大缓存条目数
       .setMaxObjectSize(1024 * 1024) // 单个缓存对象最大大小（1MB）
       .setHeuristicCachingEnabled(true) // 启用启发式缓存
       .setHeuristicDefaultLifetime(3600) // 启发式缓存默认有效期（1小时）
       .setIgnoreCacheControl(false) // 若需强制忽略服务器缓存头，可设为true（谨慎使用）
       .build();
   

2. 显式初始化FileCacheStorage
   确保使用支持持久化读取的存储实现：

   FileCacheStorage cacheStorage = new FileCacheStorage(
       cacheDir,
       1024 * 1024 * 100, // 缓存目录最大占用空间（100MB）
       1000 // 最大缓存条目数
   );
   

3. 整合配置构建客户端
   将上述配置加入CachingHttpClient构建流程：

   try (var client = CachingHttpClients.custom()
       .setCacheDir(cacheDir)
       .setDeleteCache(false)
       .setCacheConfig(cacheConfig)
       .setHttpCacheStorage(cacheStorage)
       .useSystemProperties()
       .build()) {
       // 执行请求逻辑
       HttpCacheContext context = HttpCacheContext.create();
       CloseableHttpResponse response = client.execute(new HttpGet("https://api.github.com/repos/finos/common-domain-model"), context);
       
       // 缓存状态判断
       CacheResponseStatus responseStatus = context.getCacheResponseStatus();
       switch (responseStatus) {
           case CACHE_HIT:
               System.out.println("Cache hit!");
               break;
           case CACHE_MODULE_RESPONSE:
               System.out.println("The response was generated directly by the caching module");
               break;
           case CACHE_MISS:
               System.out.println("Cache miss!");
               break;
           case VALIDATED:
               System.out.println("Cache hit after validation");
               break;
       }
   }
   

额外注意事项 #

• 确保缓存目录具备读写权限，应用进程可正常访问；
• 若服务器返回Cache-Control: no-cache，HttpClient会向服务器验证缓存有效性，此时可能显示为VALIDATED而非CACHE_HIT，属于正常逻辑；
• 避免过度修改缓存规则，尽量遵循HTTP规范，防止出现缓存不一致问题。

内容的提问来源于stack exchange，提问作者Safron