2. 缓存隔离核心原理：构建缓存key组成、输入输出哈希、模块边界定义规则

AGP 升级后，构建缓存失效频繁、跨模块增量编译不生效的根本原因在于：缓存 Key 的组成范围发生了变化。理解缓存隔离原理，就是理解 AGP 在构建过程中如何生成、匹配和复用编译中间产物。本章围绕三个核心概念展开：缓存 Key 的组成结构、输入与输出哈希的计算逻辑、以及模块边界的定义与隔离策略。

2.1 缓存 Key 的组成：从 Gradle 的 Task 到 AGP 的 Transform

在 AGP 构建体系中，每个编译步骤（如 Java 编译、Aapt2 资源打包、Dex 合并）都被抽象为一个或多个 Gradle Task。每个 Task 的输入决定了其输出的唯一性，而缓存 Key 就是这些输入的数字化摘要。

2.2 输入输出哈希：如何被计算与匹配

AGP 使用 Gradle 内置的 缓存快照（Snapshot） 机制对 Task 输入进行哈希计算。其核心路径如下：

1. 文件归集：通过 TaskInputs.file()、TaskInputs.dir() 注册输入源；AGP 7.x+ 采用 InputChanges 增量模式。
2. 快照生成：Gradle 根据文件路径、最后修改时间构建文件树哈希。AGP 8.x 引入 LazyFileHasher 优化增量扫描。
3. 输出哈希绑定：Task 的输出产物（.class、.dex、.ap_）会附带本次输入哈希的指纹，存入构建缓存。
4. 匹配判重：同一 Task 在新的构建请求中，若所有注册输入的快照哈希与缓存记录一致，则直接复用旧输出，跳过执行。

2.3 模块边界定义规则：隔离粒度与跨模块缓存

“模块边界”是指在构建图谱中，两个项目模块之间明确的编译隔离面。AGP 在升级后对边界的处理方式发生了变化：

2.4 模块边界缓存隔离的核心流程图

下图展示了从源文件变更到跨模块缓存命中与隔离的完整数据流：

2.5 模块边界定义的具体实现

在 AGP 8.x 中，模块边界通过 Transform 或 TransformManager 的作用域参数来定义。下面是一个模块边界隔离的典型配置示例：

// build.gradle.kts (模块级)
android {
    transformManager {
        // 为模块 "feature_a" 定义独立缓存域
        val moduleId = "feature_a"
        scope(moduleId) {
            variantFilter { variant ->
                variant.name == "debug"
            }
            // 输入输出缓存 Key 隔离标识
            isolateOutputBy("${moduleId}_${variant.name}")
        }
    }
}

2.6 调试与验证模块边界缓存

当需要确认模块边界隔离是否生效时，可使用以下步骤：

1. 清空缓存并执行一次全量构建：确保所有 Task 输出被正确缓存。
2. 修改一个模块的单一文件：例如在 module_b 中添加一个注释。
3. 执行增量构建并检查日志：

./gradlew :app:assembleDebug --info 2>&1 | grep "REUSED\|FROM-CACHE\|Executing task"
# 期望输出：只有 module_b 相关的 Task 被重新执行
#          module_a 和 module_c 的 Task 显示 "FROM-CACHE"

2.7 常见缓存隔离错误与性能稳定优化