如何写出兼容Configuration Cache的Gradle插件？以modules-graph-assert任务设计为例

如何写出兼容Configuration Cache的Gradle插件以modules-graph-assert任务设计为例【免费下载链接】modules-graph-assertGradle plugin to keep your modules graph healthy and lean.项目地址: https://gitcode.com/gh_mirrors/mo/modules-graph-assertmodules-graph-assert是一个帮你守护模块依赖图谱的 Gradle 插件Gradle plugin它能通过assertModuleGraph任务校验模块依赖的高度、白名单与限制规则让模块图保持健康、精简。这篇文章以它的任务设计为例拆解如何写出兼容Configuration Cache的 Gradle 插件核心思路是配置期算好数据任务期只拿可序列化的纯数据全文约 10 分钟读完。为什么 Configuration Cache 兼容对 Gradle 插件很重要从 Gradle 7 开始Configuration Cache 成为官方主推的性能优化把配置阶段的成果缓存下来后续构建跳过重复配置。但代价是——任务Task在执行时不能再访问Project对象所有传给任务的东西必须可序列化。对插件作者来说常见踩坑点有四个任务字段里持有Project、Configuration、TaskContainer等对象在TaskAction里调用project.property(...)等 API任务用tasks.create()提前创建导致配置期就执行了大量逻辑输入值Input包含不可序列化的对象modules-graph-assert 针对这四点都有明确的设计取舍下面逐个拆解。整体设计把重活放在配置阶段输出纯数据插件入口是ModuleGraphAssertionsPlugin源码见plugin/src/main/kotlin/com/jraska/module/graph/assertion/ModuleGraphAssertionsPlugin.kt。它的骨架逻辑是apply时只做两件事创建moduleGraphAssert扩展配置 DSL 的载体以及挂afterEvaluate回调真正的依赖图构建被放进lazy属性private val moduleGraph by lazy { GradleDependencyGraphFactory.create(evaluatedProject, configurationsToLook).serializableGraph() }关键点在于serializableGraph()——工厂类plugin/src/main/kotlin/com/jraska/module/graph/assertion/GradleDependencyGraphFactory.kt遍历所有子项目的api/implementation依赖构建出完整依赖图后立即把它压缩成一个只含字符串的轻量对象DependencyGraph.SerializableGraph。关键点一任务只接收 Serializable 的纯数据看断言任务的定义plugin/src/main/kotlin/com/jraska/module/graph/assertion/tasks/AssertGraphTask.ktopen class AssertGraphTask : DefaultTask() { Input lateinit var assertion: GraphAssert Input lateinit var dependencyGraph: DependencyGraph.SerializableGraph TaskAction fun run() { val modulesTree DependencyGraph.create(dependencyGraph) assertion.assert(modulesTree) } }注意这个任务没有任何 Project 字段。Input只有两个assertion规则校验器实现了GraphAssert接口而该接口继承java.io.Serializable见plugin/src/main/kotlin/com/jraska/module/graph/assertion/GraphAssert.ktdependencyGraph前面提到的可序列化图结构是模块对列表 根模块名全是字符串再看SerializableGraph的定义plugin/src/main/kotlin/com/jraska/module/graph/DependencyGraph.ktclass SerializableGraph( val dependencyPairs: ArrayListPairString, String, val firstModule: String ) : Serializable这就是兼容 Configuration Cache 的核心模式配置期访问Project获取依赖信息允许此时配置缓存还没生效然后把结果转成纯数据快照传给任务任务执行期只反序列化快照、计算断言完全不知道Project的存在。关键点二用 tasks.register 延迟创建任务插件注册任务全部走tasks.register(...)而不是tasks.create(...)project.tasks.register(Tasks.ASSERT_MAX_HEIGHT, AssertGraphTask::class.java) { it.assertion moduleTreeHeightAssert(graphRules) it.dependencyGraph moduleGraph it.outputs.upToDateWhen { true } it.group VERIFICATION_GROUP }register是惰性的——配置期只登记任务不实例化只有用户真的执行assertModuleGraph它会被挂到check任务上成为./gradlew check的一部分时才触发。这带来两个好处未执行的构建完全不触发依赖图构建moduleGraph也是lazy双保险即使执行也只在该任务真的要跑时才访问配置期数据另外断言类任务没有文件输出插件用it.outputs.upToDateWhen { true }明确告知 Gradle输入没变就视为最新让增量构建直接显示 UP-TO-DATE。关键点三属性在配置期读取而不是 TaskAction 里读GenerateModulesGraphTaskplugin/src/main/kotlin/com/jraska/module/graph/assertion/tasks/GenerateModulesGraphTask.kt需要支持-Pmodules.graph.output.gv这类项目参数。正确姿势是在任务注册的配置回调里就读完tasks.register(Tasks.GENERATE_GRAPHVIZ, GenerateModulesGraphTask::class.java) { it.outputFilePath GenerateModulesGraphTask.outputFilePath(this) it.onlyModuleToPrint GenerateModulesGraphTask.onlyModule(this) }读到的值被转成普通String?字段Input存进任务。任务执行时run()里只读自己的字段绝不再碰project.property(...)。这是新手最常犯的错误以为只是读个属性没大事结果 Configuration Cache 直接报错。还有个容易忽视的场景assertOnAnyBuild true模式要在任何构建时直接跑断言。插件用的是project.gradle.projectsEvaluated { ... }回调里直接执行断言逻辑复用同一份moduleGraph快照而不是试图在任务动作里访问 Project。如何验证兼容性两个测试用例这个项目值得学习的还有它把兼容性写进了测试集成测试plugin/src/test/kotlin/com/jraska/module/graph/assertion/ConfigurationAvoidanceTest.kt用 GradleRunner 真实构建测试工程参数带上--configuration-cache跑assertModuleGraph并断言第二次运行出现 4 个 UP-TO-DATE。这同时验证了缓存兼容和增量有效两件事。单元测试plugin/src/test/kotlin/com/jraska/module/graph/DependencyGraphSerializationTest.kt把图走一遍ObjectOutputStream→ObjectInputStream的序列化/反序列化往返断言统计结果不变——提前暴露任何漏写Serializable的字段。想在自己的插件里做同样的验证把--configuration-cache加进你的 TestKit 用例就够了。兼容 Configuration Cache 的插件检查清单把 modules-graph-assert 的做法归纳成 6 条写插件时可以逐条对照 ✅#实践对应示例1任务Input只用可序列化纯数据SerializableGraph字符串列表2任务中不持有Project引用AssertGraphTask无 Project 字段3用tasks.register惰性创建任务全部任务走register4项目参数在配置期读取为普通字段outputFilePath注册时读一次5无输出任务声明upToDateWhen { true }三个断言任务均如此6用 TestKit 序列化往返测试兜底ConfigurationAvoidanceTest小结一句话总结这套设计配置期做数据收集任务期做纯计算。modules-graph-assert 把遍历所有模块依赖的脏活封装在GradleDependencyGraphFactory里产出可序列化的图快照后任务就变成了无状态的计算单元——这正是 Gradle 官方推荐的 Configuration Cache 兼容模式。理解这一个插件的任务设计你写自己的插件尤其是涉及依赖、多项目聚合的时就已经避开了 90% 的坑。【免费下载链接】modules-graph-assertGradle plugin to keep your modules graph healthy and lean.项目地址: https://gitcode.com/gh_mirrors/mo/modules-graph-assert创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考