在多個儲存庫設定中分享建置邏輯，附帶測試套件（孵化中）範例

您可以使用 IntelliJ 原生匯入器或 Eclipse Buildship 在 IDE 中開啟此範例。

此範例顯示如何將組建邏輯組織成可重複使用的部分，並發布到儲存庫中，以在多儲存庫設定中供其他專案重複使用。

此範例顯示如何採用現有範例以搭配測試套件使用。

測試套件是孵化中的功能，且此處描述的詳細資料可能會變更。

使用案例

舉例來說，假設某個組織製作兩種 Java 軟體 - 服務和函式庫。我們想要將一組程式碼品質檢查規則套用至這兩種專案，並針對每種類型設定一些特定面向。

組織組建邏輯

此使用案例可透過分層三個獨立外掛來建模

組建邏輯配置

├── 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'
}

發布慣例外掛程式

在此範例中，我們鎖定多儲存庫設定。為了將上述外掛程式套用至個別專案，必須將它們發布至公司的成品儲存庫。慣例外掛程式是常規 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.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 是外部外掛程式 - 外部外掛程式需要新增為實作相依性，才能套用在慣例外掛程式中

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'
}

外掛程式的相依性成品座標 (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 外掛程式的詳細資訊，請參閱使用者手冊。