本文详细介绍了如何利用gradle约定插件（convention plugins）来集中管理和共享多个gradle项目间的构建逻辑，特别是针对分布在不同代码仓库中的项目。通过将重复的插件声明、依赖配置等封装成可发布的约定插件，可以显著提高构建脚本的一致性、可维护性，并简化新项目的配置过程。
引言：统一Gradle构建逻辑的挑战
在企业级或大型项目中，我们常常会遇到多个Gradle项目需要应用一套相同的构建配置，例如共同的插件集合（checkstyle、jacoco、maven-publish等）、统一的Java版本、依赖管理策略，甚至是自定义任务。如果这些项目分散在不同的代码仓库中，每次创建新项目或更新公共配置时，都需要手动复制粘贴或修改多个项目的 build.gradle 文件，这不仅效率低下，而且极易引入不一致性和错误，给项目的维护带来巨大挑战。
解决方案：Gradle约定插件
Gradle约定插件（Convention Plugins）正是为解决这类问题而生。它允许我们将一套通用的构建逻辑（包括插件应用、依赖声明、任务配置等）封装成一个独立的Gradle插件。然后，其他项目只需简单地应用这个约定插件，即可继承所有预定义的构建行为。这极大地提高了构建脚本的可重用性、可维护性和一致性。
创建约定插件项目
对于需要跨不同代码仓库共享构建逻辑的场景，最推荐的做法是将约定插件作为一个独立的Gradle项目进行开发和发布。这样，它就可以像任何其他第三方插件一样被消费项目所引用。
以下是一个创建独立约定插件项目的示例：
-
项目结构： 创建一个新的Git仓库，例如命名为 gradle-convention-plugins。其内部结构可能如下：
gradle-convention-plugins/ ├── build.gradle.kts ├── settings.gradle.kts └── src/ └── main/ └── kotlin/ └── com/ └── example/ └── convention/ ├── java-conventions.gradle.kts └── spring-boot-conventions.gradle.kts -
settings.gradle.kts：
rootProject.name = "gradle-convention-plugins"
-
build.gradle.kts (约定插件项目本身的构建文件)： 这个文件用于构建和发布我们的约定插件。我们需要应用 kotlin-dsl 插件来编写插件，并 maven-publish 插件来发布它们。
plugins { // 应用kotlin-dsl插件，以便我们可以用Kotlin编写约定插件 `kotlin-dsl` // 应用maven-publish插件，用于将约定插件发布到Maven仓库 id("maven-publish") } group = "com.example.convention" // 插件的Maven Group ID version = "1.0.0" // 插件的版本 repositories { mavenCentral() } // 配置发布 publishing { publications { create<MavenPublication>("mavenJava") { from(components["kotlinDsl"]) // 发布kotlin-dsl组件 } } repositories { // 配置发布到本地Maven仓库，实际生产中会发布到远程仓库 maven { name = "local" url = uri("${layout.buildDirectory.get()}/repo") } // 示例：发布到Artifactory或Nexus等远程仓库 // maven { // name = "myRemoteRepo" // url = uri("https://your-nexus-or-artifactory/repository/maven-releases/") // credentials { // username = System.getenv("NEXUS_USERNAME") // password = System.getenv("NEXUS_PASSWORD") // } // } } } -
定义约定插件 (.gradle.kts 文件)： 在 src/main/kotlin/com/example/convention/ 目录下创建文件，例如 java-conventions.gradle.kts，用于封装通用的Java项目配置。
// com/example/convention/java-conventions.gradle.kts plugins { id("java") id("maven-publish") // 如果Java项目需要发布，这里可以预设 id("checkstyle") id("jacoco") id("pmd") id("eclipse") // 开发者IDE支持 id("idea") // 开发者IDE支持 } java { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } repositories { mavenCentral() } // 可以在这里配置其他通用任务、依赖版本等 tasks.withType<JavaCompile>().configureEach { options.encoding = "UTF-8" } checkstyle { toolVersion = "10.12.7" // 其他checkstyle配置 } jacoco { toolVersion = "0.8.11" // 其他jacoco配置 } pmd { toolVersion = "6.55.0" // 其他pmd配置 }你还可以创建其他约定插件，例如 spring-boot-conventions.gradle.kts，它可以在 java-conventions 的基础上，进一步应用Spring Boot插件和相关配置：
// com/example/convention/spring-boot-conventions.gradle.kts plugins { // 应用我们之前定义的Java约定插件 id("com.example.convention.java-conventions") // 应用Spring Boot插件 id("org.springframework.boot") version "3.2.0" id("io.spring.dependency-management") version "1.1.4" } // Spring Boot特有的配置，例如依赖管理 dependencyManagement { imports { mavenBom(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES) } }
发布约定插件
完成约定插件的编写后，需要将其发布到Maven仓库，以便其他项目可以引用。
在 gradle-convention-plugins 项目的根目录下执行发布命令：
./gradlew publish
这会将插件发布到 build/repo 目录下（根据 publishing 配置）。在实际生产环境中，你需要配置发布到公司内部的Maven仓库，如Nexus或Artifactory。
在消费项目中应用约定插件
现在，任何独立的Gradle项目都可以通过Maven坐标来引用并应用这些约定插件。
-
配置插件仓库： 在消费项目的 settings.gradle.kts 文件中，声明约定插件所在的Maven仓库。
// settings.gradle.kts (消费项目) pluginManagement { repositories { gradlePluginPortal() // 声明约定插件所在的Maven仓库 maven { url = uri("file:///path/to/gradle-convention-plugins/build/repo") // 指向本地仓库 // url = uri("https://your-nexus-or-artifactory/repository/maven-releases/") // 指向远程仓库 } } } rootProject.name = "my-spring-boot-app"请将 file:///path/to/gradle-convention-plugins/build/repo 替换为实际的本地路径，或者替换为远程Maven仓库的URL。
-
应用约定插件： 在消费项目的 build.gradle.kts 文件中，直接应用自定义的约定插件。
// build.gradle.kts (消费项目) plugins { // 应用我们发布的Spring Boot约定插件 id("com.example.convention.spring-boot-conventions") version "1.0.0" } // 此时，所有
