Task Configuration Avoidance 与 Provider API 原理解析

Task Configuration Avoidance 解决的是配置期膨胀问题：一个构建可能注册上千个任务，但本次命令真正需要的只有几十个。

如果每次执行 ./gradlew help、./gradlew test、./gradlew :app:assembleDebug 都把所有任务创建并配置一遍，Android 多变体工程会把大量时间浪费在“本次根本不会执行的任务”上。Gradle 的答案是：先注册意图，等任务被需要时再创建。

Provider API 则是这套机制的值模型。它让构建脚本表达“这个值未来由谁提供、如何变换、什么时候读取”，而不是在配置期立刻把值算出来。

从 create 到 register 的语义变化

旧写法：

tasks.create("heavyTask") {
    println("configured")
}

这会立即创建任务对象并执行配置闭包。

现代写法：

val heavyTask = tasks.register("heavyTask") {
    println("configured")
}

这只登记一个 TaskProvider。如果本次构建不需要 heavyTask，闭包可能永远不会执行。

create:
  build script evaluation -> create task -> configure task

register:
  build script evaluation -> register provider
  task graph needs it     -> create task -> configure task

这就是“avoidance”的含义：不是配置得更快，而是根本不配置不需要的任务。

Provider 是可追踪的未来值

Gradle 的 Provider<T> 可以理解为一个带依赖关系的未来值：

val generatedDir: Provider<Directory> =
    layout.buildDirectory.dir("generated/sources")

val generatedFile: Provider<RegularFile> =
    generatedDir.map { it.file("BuildInfo.kt") }

这里没有马上创建目录，也没有马上计算最终文件。Gradle 只记录了值之间的变换关系：

buildDirectory
   |
   | map("generated/sources")
   v
generatedDir
   |
   | map("BuildInfo.kt")
   v
generatedFile

如果这个文件被某个任务输入消费，Gradle 能沿着 Provider 链追踪生产者和消费者。这比把路径转成字符串再传来传去可靠得多。

过早 get 会打破懒配置

Provider API 最大的坑是配置期调用 get()：

val output = layout.buildDirectory.file("reports/out.txt")
println(output.get().asFile.absolutePath)

这会强迫 Gradle 立刻求值。更糟的是，如果对 TaskProvider 调用 get()，会直接实现任务：

val testTask = tasks.register<Test>("integrationTest")

// 坏味道：配置期实现任务
testTask.get().dependsOn("prepareDatabase")

正确方式是继续在 provider 语义里配置：

tasks.named<Test>("integrationTest") {
    dependsOn("prepareDatabase")
}

经验规则很简单：构建脚本配置阶段看到 .get()，就要问它是否真的必须立即求值。多数情况下应使用 map、flatMap、zip、set、convention 或 configure。

只配置当前任务

Gradle 官方迁移指南特别强调：任务配置动作可能现在运行、以后运行，甚至永远不运行。因此配置闭包里只能修改当前任务，不要顺手改其他任务。

坏例子：

val check by tasks.registering

tasks.register("verificationTask") {
    check.get().dependsOn(this)
}

verificationTask 的配置闭包如果没有执行，check 就不会依赖它；如果执行时机变化，行为也会漂移。

更稳定的写法：

val verificationTask = tasks.register("verificationTask")

tasks.named("check") {
    dependsOn(verificationTask)
}

每个配置动作只改变自己的接收者，构建逻辑才具有确定性。

Android Variant API 与懒配置

AGP 现代 Variant API 也遵循类似思想。不要在配置期遍历所有 variant 后立刻创建重任务，而应在组件生命周期里注册面向 variant 的工作。

androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        val task = tasks.register<GenerateReportTask>("generate${variant.name.capitalized()}Report") {
            variantName.set(variant.name)
        }

        variant.artifacts.use(task)
            .wiredWithFiles(
                GenerateReportTask::inputFile,
                GenerateReportTask::outputFile
            )
            .toTransform(SingleArtifact.MERGED_MANIFEST)
    }
}

重点不是这段 API 细节，而是设计方向：variant、artifact、task 之间通过 Provider/Property 建立关系，由 AGP 和 Gradle 决定何时实现。

Configuration Cache 的前置条件

Task Configuration Avoidance 只减少任务配置数量；Configuration Cache 则在后续构建中跳过整个配置阶段。两者互相强化，但不是一回事。

要让 configuration cache 稳定命中，构建逻辑必须避免：

• 配置期读取不可追踪的文件和环境变量。
• 在任务对象中保存 Project、Configuration 等不可序列化运行时对象。
• 在 doLast 中访问 project 查配置。
• 配置动作中跨任务乱改状态。

Provider API 的价值在这里变得更明显：它把动态值建模为 Gradle 可追踪的输入，而不是散落在闭包里的即时读取。

迁移策略

老工程迁移时不要一次性全改。可以按风险推进：

1. 把 tasks.create、task(...) 改成 tasks.register。
2. 把 tasks.getByName 改成 tasks.named。
3. 把 all {}、withType {} 改成 configureEach。
4. 消除配置期 TaskProvider.get()。
5. 用 Build Scan 查看哪些任务被 realized。

如果改完后行为变化，通常说明旧逻辑依赖了“配置闭包一定立即执行”的副作用。修复方向不是退回 eager API，而是把副作用改成显式任务关系或 Provider 关系。

工程风险与观测清单

Task Configuration Avoidance 与 Provider API 原理解析 一旦进入真实 Android 工程，最大的风险不是单个 API 写错，而是构建行为失去可解释性：一次小改动触发大面积重编译，CI 偶发超时，缓存命中却产物不可信，或者发布后才发现某条 variant 管线没有被覆盖。

因此，学习这个主题时要同时建立两套模型：一套解释底层机制，一套解释工程风险、观测信号、回滚策略和审计边界。前者让你知道系统为什么这样运行，后者让你在生产环境里能证明它确实按预期运行。

关键风险矩阵

需要持续观测的指标

• 配置阶段耗时是否随模块数量线性或超线性增长。
• 单次本地 debug 构建的关键路径任务是谁。
• CI clean build 与 incremental build 的耗时差距。
• 远程 Build Cache 的 hit rate、miss 原因和下载耗时。
• Configuration Cache 的命中率和失效原因。
• Kotlin/Java 编译任务是否被不相关资源或依赖变化触发。
• 资源合并、DEX、R8、打包任务是否在小改动后全量重跑。
• 自定义插件是否提前实现了无关任务。
• 构建日志中是否出现未声明输入、重叠输出、deprecated API。
• 发布产物是否能追溯到唯一的源码提交、依赖锁和构建扫描。
• 失败是否可稳定复现，还是只在特定机器、特定并发下出现。
• 变更是否影响开发构建、测试构建和发布构建三条路径。

回滚与降级策略

• 构建逻辑变更与业务代码变更分开提交，便于二分定位。
• Gradle、AGP、Kotlin、JDK 升级必须保留兼容矩阵和回滚版本。
• 新插件能力先只接入一个低风险模块，再扩大到全工程。
• 远程缓存先 pull 后 push，确认产物稳定后再允许 CI 写入。
• 新增插桩、生成代码、资源处理逻辑必须提供开关。
• 发布构建失败时，优先回滚构建逻辑版本，而不是清空所有缓存碰运气。
• 对 CI 超时设置分阶段日志，确认卡在配置、依赖解析还是任务执行。
• 对不可恢复的构建产物变更记录迁移步骤，避免开发者本地状态残留。

最小验证矩阵

审计问题

1. 这段构建逻辑是否有明确所有者，还是散落在多个模块脚本里。
2. 它是否读取了没有声明为输入的文件、环境变量或系统属性。
3. 它是否在配置阶段执行了本应放到任务动作里的工作。
4. 它是否对所有 variant 生效，还是只应该对某些 variant 生效。
5. 它是否可以在没有网络、没有本地 IDE 状态的 CI 中运行。
6. 它是否把权限、密钥、签名文件路径写进了仓库。
7. 它是否破坏了并发执行，例如多个任务写同一个目录。
8. 它是否能在失败时输出足够日志，帮助定位根因。
9. 它是否能通过一个开关降级，避免阻塞全工程构建。
10. 它是否有最小复现样例或 TestKit/集成测试覆盖。
11. 它是否会让下游模块承担不必要的依赖或任务成本。
12. 它是否能在升级 Gradle/AGP 后继续工作，还是依赖内部 API。

反模式清单

• 用 clean 掩盖输入输出声明错误。
• 用 afterEvaluate 修补本可以用 Provider 表达的依赖关系。
• 用动态版本解决依赖冲突，却让构建不可复现。
• 把所有公共配置塞进一个巨型 convention plugin。
• 在 debug 构建默认开启 release 级别的重型优化。
• 在任务动作里读取 project 或全局 configuration。
• 在多个任务中共享同一个临时目录。
• 缓存命中率异常时只重启 CI，不分析 miss reason。
• 把构建扫描链接当作可选附件，而不是性能回归证据。
• 用本地 IDE 成功运行证明 CI 发布链路安全。

最小实操脚本

./gradlew help --scan
./gradlew :app:assembleDebug --scan --info
./gradlew :app:assembleDebug --build-cache --info
./gradlew :app:assembleDebug --configuration-cache
./gradlew :app:dependencies --configuration debugRuntimeClasspath
./gradlew :app:dependencyInsight --dependency <module> --configuration debugRuntimeClasspath

这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何 Task Configuration Avoidance 与 Provider API 原理解析 相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。

延伸阅读

• Gradle Task Configuration Avoidance
• Gradle Lazy Configuration
• Gradle Configuration Cache