您可以在支援 Gradle 的 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'
}

發布慣例外掛

在此範例中，我們的目標是多倉儲設定。為了將上述外掛應用於不同的專案，它們必須發布到公司的 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.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'
}

  • 外掛的相依性 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 外掛的更多詳細資訊，請參閱使用者手冊。