您可以在支持 Gradle 的 IDE 中打开此示例。

此示例展示了如何在多仓库设置中，将构建逻辑组织成可重用模块并发布到仓库，以便在其他项目中重用。

此示例展示了如何采用现有示例用于测试套件。
测试套件是处于孵化中的特性，此处描述的细节可能会发生变化。

用例

举例来说，假设一个组织开发两种类型的 Java 软件：服务（services）和库（libraries）。我们希望对这两种类型的项目应用一套代码质量检查规则，并配置一些特定于每种类型的方面。

组织构建逻辑

该用例可以通过分层三个独立的插件来建模

构建逻辑布局
├── convention-plugins
│   ├── build.gradle.kts
│   ├── settings.gradle.kts
│   ├── src
│   │   ├── main
│   │   │   └── kotlin
│   │   │       ├── com.myorg.java-conventions.gradle.kts
│   │   │       ├── com.myorg.library-conventions.gradle.kts
│   │   │       └── com.myorg.service-conventions.gradle.kts
...
构建逻辑布局
├── convention-plugins
│   ├── build.gradle
│   ├── settings.gradle
│   ├── src
│   │   ├── main
│   │   │   └── groovy
│   │   │       ├── com.myorg.java-conventions.gradle
│   │   │       ├── com.myorg.library-conventions.gradle
│   │   │       └── com.myorg.service-conventions.gradle
...

  • com.myorg.java-conventions - 配置组织中所有 Java 项目通用的约定。这适用于前面确定的两种类型的软件，因此该插件将在后续两个插件中应用。

  • com.myorg.library-conventions - 添加发布配置以发布到组织的仓库，并配置强制的文档检查。

  • com.myorg.service-conventions - 配置集成测试并检查 README 中强制包含的内容。由于服务与库不同，在此情况下配置了不同的文档要求。

此示例中创建的所有插件都包含使用 TestKit 来验证其行为的功能测试。

编译约定插件

在此示例中，约定插件被实现为预编译脚本插件 - 这是最简单的入门方式，因为您可以直接使用 Gradle 的 DSL 之一来实现构建逻辑，就像插件是一个普通的构建脚本一样。

为了让预编译脚本插件能够被发现，convention-plugins 项目需要在其 build.gradle.kts 文件中应用 kotlin-dsl 插件

为了让预编译脚本插件能够被发现，convention-plugins 项目需要在其 build.gradle 文件中应用 groovy-gradle-plugin 插件

示例 1. 启用预编译脚本插件
convention-plugins/build.gradle.kts
plugins {
    `kotlin-dsl`
}
convention-plugins/build.gradle
plugins {
    id 'groovy-gradle-plugin'
}

发布约定插件

在此示例中，我们针对的是多仓库设置。为了将上述插件应用于独立的项，必须将它们发布到公司的 artifact 仓库。约定插件是普通的 Gradle 插件 - 因此它们可以像任何其他 Gradle 插件一样发布到外部仓库。

在这里，我们配置项目使用maven-publish 插件来发布这些插件。为了演示目的，我们发布到一个本地文件系统目录。您可以在 maven-publish 插件的仓库部分找到有关如何发布到远程仓库的信息。

示例 2. 发布配置
convention-plugins/build.gradle.kts
plugins {
    `kotlin-dsl`
    `maven-publish`
}

group = "com.myorg.conventions"
version = "1.0"

publishing {
    repositories {
        maven {
            // change to point to your repo, e.g. http://my.org/repo
            url = uri(layout.buildDirectory.dir("repo"))
        }
    }
}

tasks.publish {
    dependsOn("check")
}
convention-plugins/build.gradle
plugins {
    id 'groovy-gradle-plugin'
    id 'maven-publish'
    id 'java'
}

group = 'com.myorg.conventions'
version = '1.0'

publishing {
    repositories {
        maven {
            // change to point to your repo, e.g. http://my.org/repo
            url = layout.buildDirectory.dir("repo")
        }
    }
}

tasks.named('publish') {
    dependsOn('check')
}

可以使用以下命令发布插件

./gradlew publish

为了在另一个项目中消费这些插件，请在 settings 文件中配置插件仓库并应用插件

settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
        maven {
            // replace the path with the actual path to the repository
            url = uri("<path-to>/convention-plugins/build/repo")
        }
    }
}
build.gradle.kts
plugins {
    id("com.myorg.service-conventions") version "1.0"
}
settings.gradle
pluginManagement {
    repositories {
        gradlePluginPortal()
        maven {
            // replace the path with the actual path to the repository
            url = uri('<path-to>/convention-plugins/build/repo')
        }
    }
}
build.gradle
plugins {
    id 'com.myorg.service-conventions' version '1.0'
}

注意事项

在约定插件中应用外部插件

com.myorg.java-conventions 插件使用 SpotBugs 插件执行静态代码分析。

SpotBugs 是一个外部插件 - 在约定插件中应用外部插件之前，需要将其添加为 implementation 依赖项

convention-plugins/build.gradle.kts
repositories {
    gradlePluginPortal() // so that external plugins can be resolved in dependencies section
}

dependencies {
    implementation("com.github.spotbugs.snom:spotbugs-gradle-plugin:5.2.1")
}
convention-plugins/build.gradle
repositories {
    gradlePluginPortal() // so that external plugins can be resolved in dependencies section
}

dependencies {
    implementation 'com.github.spotbugs.snom:spotbugs-gradle-plugin:5.2.1'
}

  • 插件的依赖 artifact 坐标 (GAV) 可以与插件 ID 不同。

  • Gradle 插件门户 (gradlePluginPortal()) 被添加为插件依赖项的仓库。

  • 插件版本由依赖项版本决定。

添加依赖项后，可以在约定插件中通过 ID 应用外部插件

convention-plugins/src/main/kotlin/com.myorg.java-conventions.gradle.kts
plugins {
    java
    checkstyle

    // NOTE: external plugin version is specified in implementation dependency artifact of the project's build file
    id("com.github.spotbugs")
}
convention-plugins/src/main/groovy/com.myorg.java-conventions.gradle
plugins {
    id 'java'
    id 'checkstyle'

    // NOTE: external plugin version is specified in implementation dependency artifact of the project's build file
    id 'com.github.spotbugs'
}

应用其他约定插件

约定插件可以应用其他约定插件。

com.myorg.library-conventions 和 com.myorg.service-conventions 插件都应用了 com.myorg.java-conventions 插件

convention-plugins/src/main/kotlin/com.myorg.library-conventions.gradle.kts
plugins {
    `java-library`
    `maven-publish`
    id("com.myorg.java-conventions")
}
convention-plugins/src/main/kotlin/com.myorg.service-conventions.gradle.kts
plugins {
    id("com.myorg.java-conventions")
}
convention-plugins/src/main/groovy/com.myorg.library-conventions.gradle
plugins {
    id 'java-library'
    id 'maven-publish'
    id 'com.myorg.java-conventions'
}
convention-plugins/src/main/groovy/com.myorg.service-conventions.gradle
plugins {
    id 'com.myorg.java-conventions'
}

使用主源集中的类

约定插件可以使用插件项目主源集中定义的类。

在此示例中，com.myorg.service-conventions 插件使用 src/main/java 中的自定义任务类来配置服务 README 检查

convention-plugins/src/main/kotlin/com.myorg.service-conventions.gradle.kts
val readmeCheck by tasks.registering(com.example.ReadmeVerificationTask::class) {
    readme = layout.projectDirectory.file("README.md")
    readmePatterns = listOf("^## Service API$")
}
convention-plugins/src/main/groovy/com.myorg.service-conventions.gradle
def readmeCheck = tasks.register('readmeCheck', com.example.ReadmeVerificationTask) {
    // Expect the README in the project directory
    readme = layout.projectDirectory.file("README.md")
    // README must contain a Service API header
    readmePatterns = ['^## Service API$']
}

有关编写自定义 Gradle 插件的更多详细信息，请参阅用户手册。