如何在一个多模块Gradle项目中构建并消费内部插件

本文详细介绍了在Gradle多模块项目中，如何解决子模块无法识别和使用同一项目中定义的插件的问题。核心解决方案是利用Gradle的复合构建（Composite Builds）机制，通过在根项目的`settings.gradle.kts`文件中使用`includeBuild()`指令，将插件模块作为内部构建引入。这使得Gradle能够直接从源代码构建并解析插件，避免了需要将插件发布到外部仓库的麻烦，从而实现了插件在项目内部的无缝集成和消费。

在现代软件开发中，Gradle多模块项目结构因其模块化、可重用性等优势而被广泛采用。然而，当项目内部包含一个自定义Gradle插件，并且希望该插件能被同一项目中的其他模块直接消费时，开发者可能会遇到插件无法被识别和解析的问题。本文将深入探讨这一挑战，并提供一个基于Gradle复合构建的专业解决方案。

理解问题：插件未找到

在一个典型的多模块Gradle项目中，如果一个模块（例如my-implementation）尝试应用同一项目中定义的另一个模块（例如my-gradle-plugin）提供的插件，Gradle通常会默认尝试从预配置的插件仓库（如Gradle Plugin Portal、Maven Central、Maven Local等）解析该插件。

例如，当my-implementation模块的build.gradle.kts中包含以下配置时：

plugins {
   id("org.my.gradle.plugin") version "internal" // "internal"在此处仅为占位符
}

如果my-gradle-plugin模块没有被正确地构建并发布到这些仓库中，或者Gradle没有被告知它应该从项目内部获取这个插件，那么构建过程就会失败，并抛出类似以下的错误信息：

* What went wrong:
Plugin [id: 'org.my.gradle.plugin', version: '0.0.3-SNAPSHOT'] was not found in any of the following sources:

- Gradle Core Plugins (plugin is not in 'org.gradle' namespace)
- Plugin Repositories (could not resolve plugin artifact 'org.my.gradle.plugin:org.my.gradle.plugin.gradle.plugin:0.0.3-SNAPSHOT')
  Searched in the following repositories:
    MavenLocal(file:/home/jenkins/.m2/repository/)
    maven(https://xyz)
    Gradle Central Plugin Repository
    MavenRepo

这个错误明确指出Gradle无法在任何配置的插件源中找到org.my.gradle.plugin。这是因为Gradle将内部插件视为外部依赖，而没有意识到它可以在当前构建中生成并使用该插件。

解决方案：利用复合构建（Composite Builds）

Gradle的复合构建功能允许将多个独立的Gradle构建组合成一个更大的构建。通过这种方式，主构建可以“包含”其他构建，并直接从它们的源代码中解析依赖项或插件，而无需进行发布。

要解决上述问题，核心思路是将my-gradle-plugin模块声明为一个被主构建“包含”的构建。这通过在根项目的settings.gradle.kts文件中使用includeBuild()指令来实现。

Logomaster.ai

Logo在线生成工具

99

查看详情

步骤一：配置根项目的 settings.gradle.kts

在项目的根目录下的settings.gradle.kts文件中，添加includeBuild("my-gradle-plugin")指令。这会告诉Gradle，my-gradle-plugin是一个独立的构建，其输出（包括插件）应该在当前构建中可用。

同时，在pluginManagement块中，需要配置插件仓库和解析策略。特别是，resolutionStrategy允许我们为内部插件指定版本，确保Gradle能够将org.my.gradle.plugin的请求映射到当前项目的版本。

// ./root/settings.gradle.kts

rootProject.name = "root-project"

// 包含其他子模块
include("my-api", "my-implementation")

pluginManagement {
    // 关键步骤：将插件模块作为包含构建引入
    includeBuild("my-gradle-plugin")

    repositories {
        mavenLocal()
        maven { url = uri("https://xyz") } // 你的私有Maven仓库
        gradlePluginPortal()
        mavenCentral()
    }
    resolutionStrategy {
        // 获取根项目的版本号
        val version: String by settings
        eachPlugin {
            // 当请求的插件ID是"org.my.gradle.plugin"时，使用当前项目的版本
            if (requested.id.id == "org.my.gradle.plugin") {
                useVersion(version)
            }
        }
    }
}

步骤二：插件模块的 build.gradle.kts 配置

my-gradle-plugin模块的build.gradle.kts需要正确配置以声明它是一个Gradle插件。这通常涉及应用java-gradle-plugin和maven-publish插件，并定义插件的ID、实现类和版本。

// ./root/my-gradle-plugin/build.gradle.kts

plugins {
  `java-gradle-plugin` // 声明这是一个Gradle插件项目
  `maven-publish`      // 用于发布插件（即使是内部使用，也有助于元数据生成）
}

gradlePlugin {
    plugins {
        create("myGradlePlugin") { // 创建一个插件定义
            id = "org.my.gradle.plugin"
            group = "org.my.gradle.plugin"
            implementationClass = "org.my.gradle.plugin.MyGradlePlugin" // 插件的实现类
            version = project.version // 使用项目版本
        }
    }
}

步骤三：在消费模块中应用插件

一旦根项目的settings.gradle.kts配置完成，my-implementation模块就可以像使用任何其他插件一样，直接应用内部插件了：

// ./root/my-implementation/build.gradle.kts

plugins {
   // 插件ID和版本，版本将通过settings.gradle.kts中的resolutionStrategy解析
   id("org.my.gradle.plugin") version "internal"
}

这里的version "internal"是一个约定俗成的占位符，实际的版本解析由根settings.gradle.kts中的resolutionStrategy负责，它会将org.my.gradle.plugin映射到根项目定义的版本（例如0.0.3-SNAPSHOT）。

工作原理

通过includeBuild("my-gradle-plugin")，Gradle被告知my-gradle-plugin是一个内部构建。当my-implementation模块请求org.my.gradle.plugin时，Gradle首先会在当前构建的包含构建中查找该插件，而不是直接去远程仓库。由于my-gradle-plugin已经被声明为包含构建，Gradle会负责构建它，并使其生成的插件元数据和类路径在主构建中可用，从而解决了“插件未找到”的问题。

注意事项

• Gradle版本： 本文所述的解决方案在Gradle 7.5及更高版本中验证通过。对于更旧的Gradle版本，可能需要查阅相应版本的官方文档以确认兼容性。
• 版本管理： settings.gradle.kts中的resolutionStrategy是确保插件版本正确解析的关键。它允许你集中管理内部插件的版本，使其与主项目的版本保持一致。
• 插件模块的构建： 确保my-gradle-plugin模块本身能够独立构建成功，并且正确地应用了java-gradle-plugin，这是生成Gradle插件所需元数据和类文件的基础。
• 插件的实现： 插件的实现类（如org.my.gradle.plugin.MyGradlePlugin）必须存在于my-gradle-plugin模块中，并正确实现Plugin<Project>接口。

总结

在Gradle多模块项目中内部构建和消费插件，是一个常见的需求。通过巧妙地利用Gradle的复合构建机制，特别是在根settings.gradle.kts中引入includeBuild()指令，我们可以有效地解决插件解析问题，实现插件在项目内部的无缝集成。这种方法不仅简化了开发工作流，避免了不必要的插件发布步骤，还提高了项目的内聚性和可维护性。掌握这一技巧，将使您在管理复杂的Gradle项目时更加得心应手。

以上就是如何在一个多模块Gradle项目中构建并消费内部插件的详细内容，更多请关注php中文网其它相关文章！