Gradle 插件开发全景：原理与架构选型指南

Gradle 插件不是“封装几行 build.gradle 配置”的语法糖，而是向 Gradle 构建模型注入能力的扩展单元。

一个插件被应用后，可以注册任务、创建扩展 DSL、添加依赖配置、声明 artifact 变体、接入生命周期回调，甚至改变某个项目对外发布的 metadata。Android Gradle Plugin 本身就是最复杂的 Gradle 插件之一：它读取 android {} DSL，生成 variant 模型，再注册编译、资源、打包、签名等任务图。

可以把插件想象成给工厂安装一套生产线。普通构建脚本只是在现有机器上调参数；插件会安装新机器、连接传送带、定义新的操作面板，并告诉调度系统这些机器如何协作。

插件的最小内核

最小插件只需要实现 Plugin<Project>：

class GreetingPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.tasks.register("greet") {
            it.doLast {
                println("hello from ${project.path}")
            }
        }
    }
}

apply 运行在配置阶段。这里不应该执行重型工作，而应该“建模”：注册任务、创建 extension、连接 Provider。真正耗时的文件处理、编译、网络请求，应放进任务动作，并声明输入输出。

Plugin.apply(Project)
  |
  +-- extensions.create(...)
  +-- configurations.register(...)
  +-- tasks.register(...)
  +-- dependencies.add(...)
  `-- artifacts / variants / publishing model

插件的质量，取决于它是否把构建逻辑建模成 Gradle 能理解的对象，而不是把所有逻辑塞进 afterEvaluate 或 doLast。

三类插件形态

Gradle 官方把插件实现大致分成三类：

Android 工程中最常见、性价比最高的是 precompiled convention plugin：

// build-logic/src/main/kotlin/zerobug.android.library.gradle.kts
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

android {
    compileSdk = 36
}

业务模块只应用约定：

plugins {
    id("zerobug.android.library")
}

这让模块脚本从“如何配置 Android library”退化为“我就是 Android library”。抽象边界更清晰。

插件不是全局脚本垃圾桶

把重复配置抽进插件是好事，但不要把所有东西都扔进去。插件边界应该按职责划分：

zerobug.android.application
  -> 应用模块公共配置

zerobug.android.library
  -> Android library 公共配置

zerobug.kotlin.library
  -> 纯 Kotlin/JVM 模块配置

zerobug.android.hilt
  -> DI 相关插件和依赖

zerobug.android.compose
  -> Compose 编译器和 UI 依赖

如果一个插件叫 zerobug.common，里面同时配置 Android、Kotlin、Room、Hilt、Compose、发布、测试、lint，它很快会变成另一个巨型脚本。插件也要遵守单一职责。

Extension DSL 是用户输入边界

复杂插件不应该让使用者直接改内部任务，而应暴露 extension：

abstract class ApiCheckExtension {
    abstract val enabled: Property<Boolean>
    abstract val baselineFile: RegularFileProperty
}

class ApiCheckPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        val extension = project.extensions.create(
            "apiCheck",
            ApiCheckExtension::class.java
        )

        extension.enabled.convention(true)
        extension.baselineFile.convention(
            project.layout.projectDirectory.file("api/baseline.txt")
        )

        project.tasks.register<ApiCheckTask>("apiCheck") {
            enabledFlag.set(extension.enabled)
            baselineFile.set(extension.baselineFile)
        }
    }
}

用户配置：

apiCheck {
    enabled.set(true)
    baselineFile.set(layout.projectDirectory.file("api/current.txt"))
}

这里最重要的是 Property/Provider 透传。插件不要在配置期 extension.enabled.get() 后把布尔值拷贝出来，否则用户后续配置和 lazy 语义都会被破坏。

避免 afterEvaluate 依赖

很多老插件喜欢：

project.afterEvaluate {
    val value = extension.someValue.get()
    tasks.named("someTask") {
        // 使用最终值
    }
}

afterEvaluate 像一个全局补丁钩子，短期方便，长期会让构建逻辑时序变得不可推理。现代 Gradle 插件应优先使用：

• tasks.register / tasks.named
• plugins.withId
• extensions.configure
• Provider.map / flatMap
• AGP 的 androidComponents 生命周期 API

只有在确实无法用模型关系表达时，才考虑最后兜底。

插件设计的工程检查表

一个可维护 Gradle 插件至少满足：

• 配置阶段只建模，不做耗时 I/O。
• 所有任务输入输出完整声明。
• Extension 使用 Property<T>、ListProperty<T>、RegularFileProperty 等 lazy 类型。
• 不保存 Project 到任务字段中。
• 不在任务动作里临时查询全局 configuration。
• 不依赖任务名称字符串串联复杂逻辑。
• 有 TestKit 测试覆盖关键 DSL 和任务图行为。

构建插件也是生产代码。它的 bug 可能不会直接崩溃应用，但会污染所有开发者和 CI 的构建结果。

工程风险与观测清单

Gradle 插件开发全景：原理与架构选型指南 一旦进入真实 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

这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何 Gradle 插件开发全景：原理与架构选型指南 相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。

延伸阅读

• Gradle Introduction to Plugins
• Gradle Plugin Implementation Options
• Gradle Pre-compiled Script Plugins