您可以使用 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
檔案中套用 groovy-gradle-plugin
外掛程式
為了偵測預先編譯的腳本外掛程式,convention-plugins
專案需要在其 build.gradle.kts
檔案中套用 kotlin-dsl
外掛程式
plugins {
`kotlin-dsl`
}
plugins {
id 'groovy-gradle-plugin'
}
發佈慣例外掛程式
在此範例中,我們的目標是多存放庫設定。為了將上述外掛程式套用至個別專案,必須將它們發佈至公司的成品存放庫。慣例外掛程式是常規的 Gradle 外掛程式,因此它們可以發佈至外部存放庫,就像任何其他 Gradle 外掛程式一樣。
在此,我們設定專案以使用maven-publish 外掛程式發佈外掛程式。為了示範目的,我們發佈至本機檔案系統目錄。您可以在maven-publish 外掛程式的存放庫區段中找到如何發佈至遠端存放庫的資訊。
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")
}
plugins {
id 'groovy-gradle-plugin'
id '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 = layout.buildDirectory.dir("repo")
}
}
}
tasks.named('publish') {
dependsOn('check')
}
可以使用下列方式發佈外掛程式
./gradlew publish
為了在其他專案中使用它們,請在設定檔中設定外掛程式存放庫並套用外掛程式
pluginManagement {
repositories {
gradlePluginPortal()
maven {
// replace the path with the actual path to the repository
url = uri("<path-to>/convention-plugins/build/repo")
}
}
}
plugins {
id("com.myorg.service-conventions") version "1.0"
}
pluginManagement {
repositories {
gradlePluginPortal()
maven {
// replace the path with the actual path to the repository
url = uri('<path-to>/convention-plugins/build/repo')
}
}
}
plugins {
id 'com.myorg.service-conventions' version '1.0'
}
注意事項
在慣例外掛程式中套用外部外掛程式
com.myorg.java-conventions
外掛程式使用 SpotBugs 外掛程式來執行靜態程式碼分析。
SpotBugs 是外部外掛程式,外部外掛程式需要新增為實作相依性,才能在慣例外掛程式中套用它們
repositories {
gradlePluginPortal() // so that external plugins can be resolved in dependencies section
}
dependencies {
implementation("com.github.spotbugs.snom:spotbugs-gradle-plugin:5.2.1")
testImplementation("junit:junit:4.13")
}
repositories {
gradlePluginPortal() // so that external plugins can be resolved in dependencies section
}
dependencies {
implementation 'com.github.spotbugs.snom:spotbugs-gradle-plugin:5.2.1'
testImplementation platform("org.spockframework:spock-bom:2.2-groovy-3.0")
testImplementation 'org.spockframework:spock-core'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}
tasks.named('test', Test) {
useJUnitPlatform()
}
-
外掛程式的相依性成品座標 (GAV) 可能與外掛程式 ID 不同。
-
Gradle 外掛入口網站 (
gradlePluginPortal()
) 已新增為外掛相依項的儲存庫。 -
外掛版本由相依項版本決定。
新增相依項後,外部外掛便可以在慣例外掛中透過 id 套用
plugins {
java
checkstyle
// NOTE: external plugin version is specified in implementation dependency artifact of the project's build file
id("com.github.spotbugs")
}
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
外掛
plugins {
`java-library`
`maven-publish`
id("com.myorg.java-conventions")
}
plugins {
id("com.myorg.java-conventions")
}
plugins {
id 'java-library'
id 'maven-publish'
id 'com.myorg.java-conventions'
}
plugins {
id 'com.myorg.java-conventions'
}
使用主來源設定的類別
慣例外掛可以使用外掛專案主來源設定中定義的類別。
在此範例中,com.myorg.service-conventions
外掛使用 src/main/java
中的客製化工作任務類別來設定服務 README 檢查
val readmeCheck by tasks.registering(com.example.ReadmeVerificationTask::class) {
readme = layout.projectDirectory.file("README.md")
readmePatterns = listOf("^## Service API$")
}
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 外掛的更多詳細資訊,請參閱 使用者手冊。