正在切换页面...

独立插件开发实战：Extension DSL 配置透传机制与注册解析

hardGradlePluginExtension DSLTestKitProvider API最近更新

独立 Gradle 插件适合承载复杂、可复用、需要测试和发布的构建能力。它不再依赖某个应用仓库的 build-logic，而是像普通库一样编译、测试、发布，然后被多个工程通过插件 ID 应用。

独立插件的核心难点不是“怎么写 Plugin<Project>”，而是如何设计 Extension DSL：让用户配置足够表达意图，同时保持 Gradle 的懒配置、增量构建和 configuration cache 兼容。

独立插件项目结构

一个最小 Kotlin 插件工程：

my-gradle-plugin/
├── settings.gradle.kts
├── build.gradle.kts
└── src/
    ├── main/kotlin/
    │   ├── ApiGuardExtension.kt
    │   ├── ApiGuardPlugin.kt
    │   └── ApiGuardTask.kt
    └── test/kotlin/
        └── ApiGuardPluginTest.kt

构建文件：

plugins {
    `java-gradle-plugin`
    `kotlin-dsl`
}

gradlePlugin {
    plugins {
        create("apiGuard") {
            id = "club.zerobug.api-guard"
            implementationClass = "club.zerobug.gradle.ApiGuardPlugin"
        }
    }
}

java-gradle-plugin 会生成插件 marker metadata，让消费者能通过 plugins { id("club.zerobug.api-guard") version "..." } 应用。

Extension 是插件的公共契约

不要让用户直接配置内部任务：

tasks.named<ApiGuardTask>("apiGuard") {
    // 暴露内部任务名，后续重构会破坏用户脚本
}

应提供稳定 extension：

abstract class ApiGuardExtension @Inject constructor(objects: ObjectFactory) {
    val enabled: Property<Boolean> = objects.property(Boolean::class.java)
    val apiFile: RegularFileProperty = objects.fileProperty()
    val failOnChange: Property<Boolean> = objects.property(Boolean::class.java)
}

插件实现：

class ApiGuardPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        val extension = project.extensions.create(
            "apiGuard",
            ApiGuardExtension::class.java
        )

        extension.enabled.convention(true)
        extension.failOnChange.convention(true)
        extension.apiFile.convention(
            project.layout.projectDirectory.file("api/current.txt")
        )

        project.tasks.register<ApiGuardTask>("apiGuard") {
            enabledFlag.set(extension.enabled)
            apiFile.set(extension.apiFile)
            failOnChange.set(extension.failOnChange)
        }
    }
}

这段代码没有在配置期读取 extension 值，而是把 Provider 关系传给任务。用户在插件应用后继续配置 extension，任务仍能拿到最终值。

任务字段不能保存 Project

任务实现要保持可序列化、可缓存：

abstract class ApiGuardTask : DefaultTask() {
    @get:Input
    abstract val enabledFlag: Property<Boolean>

    @get:InputFile
    @get:PathSensitive(PathSensitivity.RELATIVE)
    abstract val apiFile: RegularFileProperty

    @get:Input
    abstract val failOnChange: Property<Boolean>

    @TaskAction
    fun run() {
        if (!enabledFlag.get()) {
            logger.lifecycle("apiGuard disabled")
            return
        }

        val file = apiFile.get().asFile
        if (!file.exists() && failOnChange.get()) {
            throw GradleException("API file does not exist: ${file.path}")
        }
    }
}

不要在任务字段中保存 Project、Configuration、SourceSetContainer。这些对象属于配置期模型，不适合进入 execution-time task state。任务动作所需的所有东西，都应该以 Property 或文件属性注入。

插件内部如何响应其他插件

独立插件经常需要在 Android、Java、Kotlin 插件存在时接入不同逻辑。不要假设插件应用顺序：

project.plugins.withId("com.android.application") {
    configureAndroidApp(project, extension)
}

project.plugins.withId("java-library") {
    configureJavaLibrary(project, extension)
}

plugins.withId 表达的是“当某插件存在时执行配置”。它比在 apply 里立即查找 extension 更稳，因为消费者可以先应用你的插件，也可以后应用 Android 插件。

TestKit 验证的是真实构建行为

插件测试不能只测普通函数。Gradle TestKit 可以创建临时工程，执行真实 Gradle 构建：

class ApiGuardPluginTest {
    @Test
    fun `registers api guard task`() {
        val projectDir = Files.createTempDirectory("api-guard-test").toFile()
        projectDir.resolve("settings.gradle.kts").writeText("")
        projectDir.resolve("build.gradle.kts").writeText(
            """
            plugins {
                id("club.zerobug.api-guard")
            }
            """.trimIndent()
        )

        val result = GradleRunner.create()
            .withProjectDir(projectDir)
            .withArguments("tasks", "--all")
            .withPluginClasspath()
            .build()

        assertTrue(result.output.contains("apiGuard"))
    }
}

TestKit 的价值是覆盖插件 marker、脚本编译、任务注册、DSL 配置、configuration cache 等真实路径。构建插件如果没有这种测试，很容易在发布后才发现某个 Gradle 版本或 Android 插件顺序下失效。

发布与兼容性策略

独立插件要像公开 API 一样管理兼容性：

插件 ID 一旦发布不要随意修改。
Extension 字段只能兼容新增，删除和改名要有迁移期。
明确支持的 Gradle、AGP、Kotlin 版本范围。
不直接依赖内部 Gradle API 或 AGP internal 包。
对弃用 API 设置 CI 检查。

构建插件运行在所有开发者机器和 CI 上，它的兼容性问题会直接阻塞交付。宁愿 API 设计保守，也不要把未稳定的内部对象暴露给使用者。

工程风险与观测清单

独立插件开发实战：Extension DSL 配置透传机制与注册解析一旦进入真实 Android 工程，最大的风险不是单个 API 写错，而是构建行为失去可解释性：一次小改动触发大面积重编译，CI 偶发超时，缓存命中却产物不可信，或者发布后才发现某条 variant 管线没有被覆盖。

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

关键风险矩阵

风险点	触发条件	直接后果	观测方式	缓解策略
输入声明缺失	构建逻辑读取未声明文件或环境变量	UP-TO-DATE 或缓存结果错误	使用 `--info` 和 Build Scan 查看输入变化	把所有影响输出的状态建模为 `@Input` 或 Provider
绝对路径泄漏	任务 key 包含本机路径	CI 与本地缓存无法复用	对比不同机器的 cache key 变化	使用相对路径敏感性和路径归一化
配置期副作用	build script 执行 I/O、Git、网络请求	任意命令都变慢，configuration cache 失效	执行 `help --scan` 观察配置期耗时	把副作用移动到任务动作并声明输入输出
Variant 污染	对所有 variant 注册重型任务	debug 构建被 release 逻辑拖慢	查看 realized tasks 和 task timeline	使用 selector 精确匹配目标 variant
权限外溢	插件或脚本读取 CI secret、用户目录	构建不可复现，存在供应链风险	审计构建日志和环境变量访问	使用最小权限和显式 secret 注入
并发竞争	多个任务写同一输出目录	产物互相覆盖或偶发失败	检查 overlapping outputs 报告	每个任务拥有独立输出目录
缓存污染	不可信分支向远程缓存 push	全团队复用错误产物	统计 remote cache push 来源	只允许受信任 CI 写入远程缓存
回滚困难	构建逻辑与业务变更混在一起	发布失败时无法快速定位	变更审计和构建 scan 对比	构建逻辑独立提交、独立验证
降级缺口	新 Gradle/AGP API 无兜底策略	升级失败后阻塞全线开发	记录兼容矩阵和失败任务	保留可回滚版本和迁移开关
资源释放遗漏	自定义任务打开文件句柄或进程未关闭	Windows/CI 上清理失败或锁文件	观察 daemon 日志和文件锁错误	使用 Worker API 或 try/finally 释放资源

需要持续观测的指标

配置阶段耗时是否随模块数量线性或超线性增长。
单次本地 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 超时设置分阶段日志，确认卡在配置、依赖解析还是任务执行。
对不可恢复的构建产物变更记录迁移步骤，避免开发者本地状态残留。

最小验证矩阵

验证场景	命令或动作	期望信号
空任务配置成本	`./gradlew help --scan`	配置期没有无关重任务
本地增量构建	连续执行同一 assemble 任务	第二次大量任务 UP-TO-DATE
缓存复用	清理输出后启用 build cache	可缓存任务出现 FROM-CACHE
Variant 隔离	分别构建 debug/release	只出现目标 variant 相关任务
CI 可复现	干净工作区执行 release 构建	不依赖本机隐藏文件
依赖稳定	执行 dependencyInsight	版本选择可解释，无动态漂移
配置缓存	`--configuration-cache` 连跑两次	第二次复用配置缓存
发布审计	记录 scan、mapping、签名信息	产物可追溯、可回滚

审计问题

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

这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何独立插件开发实战：Extension DSL 配置透传机制与注册解析相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。

独立插件开发实战：Extension DSL 配置透传机制与注册解析

hardGradlePluginExtension DSLTestKitProvider API最近更新

独立插件项目结构

一个最小 Kotlin 插件工程：

my-gradle-plugin/
├── settings.gradle.kts
├── build.gradle.kts
└── src/
    ├── main/kotlin/
    │   ├── ApiGuardExtension.kt
    │   ├── ApiGuardPlugin.kt
    │   └── ApiGuardTask.kt
    └── test/kotlin/
        └── ApiGuardPluginTest.kt

构建文件：

plugins {
    `java-gradle-plugin`
    `kotlin-dsl`
}

gradlePlugin {
    plugins {
        create("apiGuard") {
            id = "club.zerobug.api-guard"
            implementationClass = "club.zerobug.gradle.ApiGuardPlugin"
        }
    }
}

java-gradle-plugin 会生成插件 marker metadata，让消费者能通过 plugins { id("club.zerobug.api-guard") version "..." } 应用。

Extension 是插件的公共契约

不要让用户直接配置内部任务：

tasks.named<ApiGuardTask>("apiGuard") {
    // 暴露内部任务名，后续重构会破坏用户脚本
}

应提供稳定 extension：

abstract class ApiGuardExtension @Inject constructor(objects: ObjectFactory) {
    val enabled: Property<Boolean> = objects.property(Boolean::class.java)
    val apiFile: RegularFileProperty = objects.fileProperty()
    val failOnChange: Property<Boolean> = objects.property(Boolean::class.java)
}

插件实现：

class ApiGuardPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        val extension = project.extensions.create(
            "apiGuard",
            ApiGuardExtension::class.java
        )

        extension.enabled.convention(true)
        extension.failOnChange.convention(true)
        extension.apiFile.convention(
            project.layout.projectDirectory.file("api/current.txt")
        )

        project.tasks.register<ApiGuardTask>("apiGuard") {
            enabledFlag.set(extension.enabled)
            apiFile.set(extension.apiFile)
            failOnChange.set(extension.failOnChange)
        }
    }
}

这段代码没有在配置期读取 extension 值，而是把 Provider 关系传给任务。用户在插件应用后继续配置 extension，任务仍能拿到最终值。

任务字段不能保存 Project

任务实现要保持可序列化、可缓存：

abstract class ApiGuardTask : DefaultTask() {
    @get:Input
    abstract val enabledFlag: Property<Boolean>

    @get:InputFile
    @get:PathSensitive(PathSensitivity.RELATIVE)
    abstract val apiFile: RegularFileProperty

    @get:Input
    abstract val failOnChange: Property<Boolean>

    @TaskAction
    fun run() {
        if (!enabledFlag.get()) {
            logger.lifecycle("apiGuard disabled")
            return
        }

        val file = apiFile.get().asFile
        if (!file.exists() && failOnChange.get()) {
            throw GradleException("API file does not exist: ${file.path}")
        }
    }
}

插件内部如何响应其他插件

独立插件经常需要在 Android、Java、Kotlin 插件存在时接入不同逻辑。不要假设插件应用顺序：

project.plugins.withId("com.android.application") {
    configureAndroidApp(project, extension)
}

project.plugins.withId("java-library") {
    configureJavaLibrary(project, extension)
}

TestKit 验证的是真实构建行为

插件测试不能只测普通函数。Gradle TestKit 可以创建临时工程，执行真实 Gradle 构建：

class ApiGuardPluginTest {
    @Test
    fun `registers api guard task`() {
        val projectDir = Files.createTempDirectory("api-guard-test").toFile()
        projectDir.resolve("settings.gradle.kts").writeText("")
        projectDir.resolve("build.gradle.kts").writeText(
            """
            plugins {
                id("club.zerobug.api-guard")
            }
            """.trimIndent()
        )

        val result = GradleRunner.create()
            .withProjectDir(projectDir)
            .withArguments("tasks", "--all")
            .withPluginClasspath()
            .build()

        assertTrue(result.output.contains("apiGuard"))
    }
}

发布与兼容性策略

独立插件要像公开 API 一样管理兼容性：

插件 ID 一旦发布不要随意修改。
Extension 字段只能兼容新增，删除和改名要有迁移期。
明确支持的 Gradle、AGP、Kotlin 版本范围。
不直接依赖内部 Gradle API 或 AGP internal 包。
对弃用 API 设置 CI 检查。

构建插件运行在所有开发者机器和 CI 上，它的兼容性问题会直接阻塞交付。宁愿 API 设计保守，也不要把未稳定的内部对象暴露给使用者。

工程风险与观测清单

关键风险矩阵

风险点	触发条件	直接后果	观测方式	缓解策略
输入声明缺失	构建逻辑读取未声明文件或环境变量	UP-TO-DATE 或缓存结果错误	使用 `--info` 和 Build Scan 查看输入变化	把所有影响输出的状态建模为 `@Input` 或 Provider
绝对路径泄漏	任务 key 包含本机路径	CI 与本地缓存无法复用	对比不同机器的 cache key 变化	使用相对路径敏感性和路径归一化
配置期副作用	build script 执行 I/O、Git、网络请求	任意命令都变慢，configuration cache 失效	执行 `help --scan` 观察配置期耗时	把副作用移动到任务动作并声明输入输出
Variant 污染	对所有 variant 注册重型任务	debug 构建被 release 逻辑拖慢	查看 realized tasks 和 task timeline	使用 selector 精确匹配目标 variant
权限外溢	插件或脚本读取 CI secret、用户目录	构建不可复现，存在供应链风险	审计构建日志和环境变量访问	使用最小权限和显式 secret 注入
并发竞争	多个任务写同一输出目录	产物互相覆盖或偶发失败	检查 overlapping outputs 报告	每个任务拥有独立输出目录
缓存污染	不可信分支向远程缓存 push	全团队复用错误产物	统计 remote cache push 来源	只允许受信任 CI 写入远程缓存
回滚困难	构建逻辑与业务变更混在一起	发布失败时无法快速定位	变更审计和构建 scan 对比	构建逻辑独立提交、独立验证
降级缺口	新 Gradle/AGP API 无兜底策略	升级失败后阻塞全线开发	记录兼容矩阵和失败任务	保留可回滚版本和迁移开关
资源释放遗漏	自定义任务打开文件句柄或进程未关闭	Windows/CI 上清理失败或锁文件	观察 daemon 日志和文件锁错误	使用 Worker API 或 try/finally 释放资源

需要持续观测的指标

配置阶段耗时是否随模块数量线性或超线性增长。
单次本地 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 超时设置分阶段日志，确认卡在配置、依赖解析还是任务执行。
对不可恢复的构建产物变更记录迁移步骤，避免开发者本地状态残留。

最小验证矩阵

验证场景	命令或动作	期望信号
空任务配置成本	`./gradlew help --scan`	配置期没有无关重任务
本地增量构建	连续执行同一 assemble 任务	第二次大量任务 UP-TO-DATE
缓存复用	清理输出后启用 build cache	可缓存任务出现 FROM-CACHE
Variant 隔离	分别构建 debug/release	只出现目标 variant 相关任务
CI 可复现	干净工作区执行 release 构建	不依赖本机隐藏文件
依赖稳定	执行 dependencyInsight	版本选择可解释，无动态漂移
配置缓存	`--configuration-cache` 连跑两次	第二次复用配置缓存
发布审计	记录 scan、mapping、签名信息	产物可追溯、可回滚

审计问题

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

独立插件开发实战：Extension DSL 配置透传机制与注册解析

独立插件项目结构

Extension 是插件的公共契约

任务字段不能保存 Project

插件内部如何响应其他插件

TestKit 验证的是真实构建行为

发布与兼容性策略

工程风险与观测清单

关键风险矩阵

需要持续观测的指标

回滚与降级策略

最小验证矩阵

审计问题

反模式清单

最小实操脚本

延伸阅读

独立插件开发实战：Extension DSL 配置透传机制与注册解析

独立插件项目结构

Extension 是插件的公共契约

任务字段不能保存 Project

插件内部如何响应其他插件

TestKit 验证的是真实构建行为

发布与兼容性策略

工程风险与观测清单

关键风险矩阵

需要持续观测的指标

回滚与降级策略

最小验证矩阵

审计问题

反模式清单

最小实操脚本

延伸阅读