4. 创建 OkHttpClient 并配置缓存：Cache 对象构造、maxSize、directory、缓存目录权限

4.1 原理：缓存数据落地的核心结构

OkHttp 的缓存子系统基于磁盘缓存（DiskLruCache）实现。在 OkHttpClient 构造时，通过传入一个 Cache 对象来启用缓存功能。该对象负责管理缓存文件的生命周期，包括存储、读取、淘汰和清理。

Cache 对象的构造需要三个核心参数：

• directory（缓存目录）：指定缓存数据存储的磁盘路径，通常为应用的缓存子目录。
• maxSize（最大字节数）：缓存文件的总容量上限，达到上限后 OkHttp 会自动淘汰最久未使用的条目。
• fileSystem（可选）：文件系统抽象层，默认使用 FileSystem.SYSTEM，无特殊需求无需修改。

上图展示了 Cache 对象的三个核心参数及其在磁盘上的文件系统组织结构。当应用通过 OkHttpClient 发起网络请求并命中缓存时，OkHttp 会从这些文件中读取响应数据。

4.2 实现流程：构建 Cache 对象并注入 OkHttpClient

4.2.1 步骤一：选择缓存目录

在 Android 应用中，推荐使用 context.cacheDir 作为缓存根目录，系统会自动管理该目录的清理行为。

4.2.2 步骤二：确定缓存大小

maxSize 的值直接影响缓存命中率和磁盘占用。下表列出不同应用场景的推荐值：

应用类型	建议 maxSize	理由
即时通讯	10~20 MiB	文本/小图片为主，更新频率高
电商/新闻	50~100 MiB	大量图片与列表数据，适度缓存可提升体验
视频/直播	100~200 MiB	封面图/配置等元数据需缓存，流媒体内容不缓存
工具类	5~20 MiB	请求量少，以实时性为主

4.2.3 步骤三：构造 Cache 对象并创建 OkHttpClient

以下是完整的 Kotlin 代码示例（Java 版本见代码块下方）：

// Kotlin 示例
val cacheDirectory = File(context.cacheDir, "okhttp_cache")
val cacheSize = 50L * 1024 * 1024   // 50 MiB
val cache = Cache(cacheDirectory, cacheSize)

val client = OkHttpClient.Builder()
    .cache(cache)
    .build()

// Java 示例
File cacheDirectory = new File(context.getCacheDir(), "okhttp_cache");
long cacheSize = 50L * 1024 * 1024;   // 50 MiB
Cache cache = new Cache(cacheDirectory, cacheSize);

OkHttpClient client = new OkHttpClient.Builder()
    .cache(cache)
    .build();

4.3 缓存目录权限问题与解决

4.3.1 权限检查流程

Cache 构造函数内部会对目录执行以下检查：

• 目录是否存在，若不存在则尝试创建（包括父目录）。
• 验证目录是否为普通目录（非文件、非符号链接等）。
• 确认应用对该目录具有读、写和执行权限。

如果权限不足，OkHttp 会抛出 java.io.IOException，并携带类似以下日志的信息：

java.io.IOException: cache directory /data/data/com.example.app/cache/okhttp_cache
exists but is not readable/writable/executable

4.3.2 常见原因与修复方案

错误场景	原因	解决方案
目录路径不可写	传入的路径指向外部存储但未声明权限，或 Android 11+ 分区存储限制	使用 context.cacheDir 内部存储
父目录不存在	Cache 未自动创建多级父目录	手动确保父目录存在：cacheDirectory.mkdirs()
SELinux 策略限制	系统加固导致应用无法操作指定目录	检测 SecurityException，回退到内部存储
并发创建冲突	多个进程或线程同时创建同一目录	使用 synchronized 或 FileLock

4.4 调试与验证

创建 Cache 对象后，可以通过以下方式快速验证其工作状态：

4.4.1 打印缓存统计信息

// 发送一次请求后，在日志中查看缓存状态
client.cache()?.let { cache ->
    Log.d("CacheStats", """
        Request Count: ${cache.requestCount()}
        Network Count: ${cache.networkCount()}
        Hit Count:     ${cache.hitCount()}
        Miss Count:    ${cache.missCount()}
    """.trimIndent())
}

4.4.2 检查缓存目录内容

使用 ADB shell 直接读取缓存文件列表：

adb shell
run-as com.example.app
ls -la /data/data/com.example.app/cache/okhttp_cache
# 正常输出应包含：journal 文件以及多个带有 .0 和 .1 扩展名的条目文件

如果目录为空（只有 journal），说明尚未发生任何网络请求；如果出现 journal.tmp 文件，则可能是异常中断导致的，OkHttp 会在下次启动时自动恢复。

4.5 常见错误与修复

错误日志	原因	修复措施
IOException: Content-Length mismatch	缓存文件大小与 HTTP 声明的 Content-Length 不一致	检查后端是否返回了 Content-Length 但实际传输数据不匹配；开启 OkHttp 日志拦截器排查
IllegalStateException: cache already used	同一个 Cache 对象被多个 OkHttpClient 共享	每个 OkHttpClient 实例使用独立的 Cache 对象
IOException: journal file not found	journal 文件被外部进程删除	OkHttp 会自动重建；定期检查目录完整性，避免手动删除
OutOfMemoryError	maxSize 设置过大（如 >500 MiB），导致内存映射压力	Android 设备推荐 ≤200 MiB，具体依可用内存调整

4.6 稳定性与性能优化建议

• 延迟初始化：Cache 构造本身不耗时，但建议在应用启动时异步创建，避免阻塞冷启动。
• 文件系统选择：始终使用 FileSystem.SYSTEM（默认），不要自定义 FileSystem 实现，除非有非常特殊的加密或隔离需求。
• maxSize 预热：首次创建时如果旧缓存占满目录，OkHttp 会立即执行 cleanUp() 淘汰文件，可能造成短时 I/O 压力。可以设置一个稍小的初始值，后续再动态调整。
• 静默恢复：当缓存目录被删除或损坏时，OkHttp 会自动重新创建目录并初始化新的 journal 文件，无需手动干预。
• 监控告警：在调试构建中定期检查 cache.hitRate()（命中率 = hitCount / requestCount），若 < 10% 表示配置不合理或服务器缓存头设置有问题。