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

若要為軟體專案做好成長準備，您可以將 Gradle 專案整理成多個子專案，以模組化您正在建構的軟體。在本指南中，您將學習如何以 Groovy 應用程式的範例來建構此類專案。不過，一般概念適用於您使用 Gradle 建構的任何軟體。您可以逐步遵循指南從頭開始建立新專案，或使用上方連結下載完整的範例專案。

您將建立的內容

您將建立一個 Groovy 應用程式，其中包含一個應用程式和多個函式庫專案。

您需要的內容

建立專案資料夾

Gradle 內建一個名為 init 的任務，可以在空的資料夾中初始化新的 Gradle 專案。init 任務會使用（也內建）的 wrapper 任務來建立 Gradle wrapper 腳本 gradlew。

第一步是為新專案建立一個資料夾並切換目錄到該資料夾。

$ mkdir demo
$ cd demo

執行 init 任務

在新的專案目錄中，使用終端機中的以下指令執行 init 任務：gradle init。提示時，選擇 1: application 專案類型和 3: Groovy 作為實作語言。之後，選擇 2: Add library projects。接下來，您可以選擇用於撰寫建置腳本的 DSL - 1 : Groovy 或 2: Kotlin。對於其他問題，按 Enter 使用預設值。

輸出會如下所示

$ gradle init

Select type of project to generate:
  1: basic
  2: application
  3: library
  4: Gradle plugin
Enter selection (default: basic) [1..4] 1

Split functionality across multiple subprojects?:
   1: no - only one application project
   2: yes - application and library projects
Enter selection (default: no - only one application project) [1..2] 2

Select implementation language:
  1: C++
  2: Groovy
  3: Java
  4: Kotlin
  5: Scala
  6: Swift
Enter selection (default: Java) [1..6] 3

Select build script DSL:
  1: Groovy
  2: Kotlin
Enter selection (default: Groovy) [1..2] 1

Project name (default: demo):
Source package (default: demo):


BUILD SUCCESSFUL
2 actionable tasks: 2 executed

init 任務會產生具有以下結構的新專案

├── gradle (1)
│   ├── libs.versions.toml (2)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew (3)
├── gradlew.bat (3)
├── settings.gradle.kts (4)
├── buildSrc
│   ├── build.gradle.kts (5)
│   ├── settings.gradle.kts (5)
│   └── src
│       └── main
│           └── kotlin (6)
│               ├── buildlogic.groovy-application-conventions.gradle.kts
│               ├── buildlogic.groovy-common-conventions.gradle.kts
│               └── buildlogic.groovy-library-conventions.gradle.kts
├── app
│   ├── build.gradle.kts (7)
│   └── src
│       ├── main (8)
│       │   └── java
│       │       └── demo
│       │           └── app
│       │               ├── App.java
│       │               └── MessageUtils.groovy
│       └── test (9)
│           └── java
│               └── demo
│                   └── app
│                       └── MessageUtilsTest.groovy
├── list
│   ├── build.gradle.kts (7)
│   └── src
│       ├── main (8)
│       │   └── java
│       │       └── demo
│       │           └── list
│       │               └── LinkedList.groovy
│       └── test (9)
│           └── java
│               └── demo
│                   └── list
│                       └── LinkedListTest.groovy
└── utilities
    ├── build.gradle.kts (7)
    └── src
        └── main (8)
            └── java
                └── demo
                    └── utilities
                        ├── JoinUtils.groovy
                        ├── SplitUtils.groovy
                        └── StringUtils.groovy
├── gradle (1)
│   ├── libs.versions.toml (2)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew (3)
├── gradlew.bat (3)
├── settings.gradle (4)
├── buildSrc
│   ├── build.gradle (5)
│   ├── settings.gradle (5)
│   └── src
│       └── main
│           └── groovy (6)
│               ├── buildlogic.groovy-application-conventions.gradle
│               ├── buildlogic.groovy-common-conventions.gradle
│               └── buildlogic.groovy-library-conventions.gradle
├── app
│   ├── build.gradle (7)
│   └── src
│       ├── main (8)
│       │   └── java
│       │       └── demo
│       │           └── app
│       │               ├── App.java
│       │               └── MessageUtils.java
│       └── test (9)
│           └── java
│               └── demo
│                   └── app
│                       └── MessageUtilsTest.java
├── list
│   ├── build.gradle (7)
│   └── src
│       ├── main (8)
│       │   └── java
│       │       └── demo
│       │           └── list
│       │               └── LinkedList.java
│       └── test (9)
│           └── java
│               └── demo
│                   └── list
│                       └── LinkedListTest.java
└── utilities
    ├── build.gradle (7)
    └── src
        └── main (8)
            └── java
                └── demo
                    └── utilities
                        ├── JoinUtils.java
                        ├── SplitUtils.java
                        └── StringUtils.java
1 為 wrapper 檔案產生的資料夾
2 產生的版本目錄
3 Gradle wrapper 啟動腳本
4 設定檔用於定義建置名稱和子專案
5 buildSrc 的建置腳本用於設定建置邏輯的相依性
6 使用 Groovy 或 Kotlin DSL 撰寫的慣例外掛的原始碼資料夾
7 三個子專案的建置腳本 - app、list 和 utilities
8 每個子專案中的 Groovy 原始碼資料夾
9 子專案中的 Groovy 測試原始碼資料夾

現在您已經設定好專案，可以建置一個模組化為多個子專案的 Groovy 應用程式。

檢閱專案檔案

settings.gradle(.kts) 檔案中有兩行有趣的程式碼

settings.gradle.kts
rootProject.name = "demo"
include("app", "list", "utilities")
settings.gradle
rootProject.name = 'demo'
include('app', 'list', 'utilities')

  • rootProject.name 會指定一個名稱給建置，這會覆寫根據建置所在目錄來命名建置的預設行為。建議設定一個固定的名稱，因為如果專案是共用的，資料夾可能會變更 - 例如，作為 Git 儲存庫的根目錄。

  • include("app", "list", "utilities") 定義建置包含對應資料夾中的三個子專案。可以透過延伸清單或新增更多 include(…​) 陳述式來新增更多子專案。

由於我們的建置包含多個子專案，我們想要在它們之間分享建置邏輯和設定。為此，我們使用位於 buildSrc 資料夾中的所謂慣例外掛程式。buildSrc 中的慣例外掛程式是利用 Gradle 的外掛程式系統撰寫可重複使用的建置設定區段的簡便方式。

在這個範例中，我們可以找到三個基於彼此的此類慣例外掛程式

buildSrc/src/main/kotlin/buildlogic.groovy-common-conventions.gradle.kts
plugins {
    groovy (1)
}

repositories {
    mavenCentral() (2)
}

dependencies {
    constraints {
        implementation("org.apache.commons:commons-text:1.11.0") (3)

        implementation("org.codehaus.groovy:groovy-all:3.0.19")
    }

    implementation("org.codehaus.groovy:groovy-all") (4)

    testImplementation("org.junit.jupiter:junit-jupiter:5.10.1") (5)

    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.named<Test>("test") {
    useJUnitPlatform() (6)
}
buildSrc/src/main/groovy/buildlogic.groovy-common-conventions.gradle
plugins {
    id 'groovy' (1)
}

repositories {
    mavenCentral() (2)
}

dependencies {
    constraints {
        implementation 'org.apache.commons:commons-text:1.11.0' (3)

        implementation 'org.codehaus.groovy:groovy-all:3.0.19'
    }

    implementation 'org.codehaus.groovy:groovy-all' (4)

    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.1' (5)

    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

tasks.named('test') {
    useJUnitPlatform() (6)
}

groovy-common-conventions 定義一些設定，所有我們的 Groovy 專案都應該共用這些設定，無論它們是代表函式庫或實際應用程式。首先，我們套用 Groovy 外掛程式 (1) 以便可以使用建置 Groovy 專案的所有功能。然後，我們宣告一個存放庫 — mavenCentral() — 作為外部相依項目的來源 (2)，定義相依項目限制 (3) 以及所有子專案共用的標準相依項目，並將 JUnit 5 設定為測試架構 (4…​)。其他共用設定，例如編譯器旗標或 JVM 版本相容性，也可以在此設定。

buildSrc/src/main/kotlin/buildlogic.groovy-library-conventions.gradle.kts
plugins {
    id("buildlogic.groovy-common-conventions") (1)
    `java-library` (2)
}
buildSrc/src/main/groovy/buildlogic.groovy-library-conventions.gradle
plugins {
    id 'buildlogic.groovy-common-conventions' (1)
    id 'java-library' (2)
}
buildSrc/src/main/kotlin/buildlogic.groovy-application-conventions.gradle.kts
plugins {
    id("buildlogic.groovy-common-conventions") (1)
    application (2)
}
buildSrc/src/main/groovy/buildlogic.groovy-application-conventions.gradle
plugins {
    id 'buildlogic.groovy-common-conventions' (1)
    id 'application' (2)
}

groovy-library-conventions 和 groovy-application-conventions 都套用 groovy-common-conventions 外掛程式 (1)，因此在那裡執行的設定會由函式庫和應用程式專案共用。接著，它們分別套用 java-library 或 application 外掛程式 (2)，因此將我們的共用設定邏輯與函式庫或應用程式的特定設定結合在一起。雖然這個範例中沒有更精細的設定，但函式庫或應用程式專案特定的建置設定可以放入這些慣例外掛程式指令碼中。

讓我們看看子專案中的 build.gradle(.kts) 檔案。

app/build.gradle.kts
plugins {
    id("buildlogic.groovy-application-conventions")
}

dependencies {
    implementation("org.apache.commons:commons-text")
    implementation(project(":utilities"))
}

application {
    mainClass = "demo.app.App" (1)
}
app/build.gradle
plugins {
    id 'buildlogic.groovy-application-conventions'
}

dependencies {
    implementation 'org.apache.commons:commons-text'
    implementation project(':utilities')
}

application {
    mainClass = 'demo.app.App' (1)
}
list/build.gradle.kts
plugins {
    id("buildlogic.groovy-library-conventions")
}
list/build.gradle
plugins {
    id 'buildlogic.groovy-library-conventions'
}
utilities/build.gradle.kts
plugins {
    id("buildlogic.groovy-library-conventions")
}

dependencies {
    api(project(":list"))
}
utilities/build.gradle
plugins {
    id 'buildlogic.groovy-library-conventions'
}

dependencies {
    api project(':list')
}

檢視建置指令碼，我們可以看到它們包含多達三個區塊

  • 每個建置指令碼都應該有一個 plugins {} 區塊來套用外掛程式。在結構良好的建置中，它可能只套用一個慣例外掛程式，就像這個範例中一樣。然後，慣例外掛程式將負責套用和設定核心 Gradle 外掛程式（例如 application 或 java-library）、其他慣例外掛程式或外掛程式入口網站中的社群外掛程式。

  • 其次，如果專案有相依性，應該新增 dependencies {} 區塊。相依性可以是外部的，例如我們在 groovy-common-conventions 中新增的 JUnit 相依性，或者可以指向其他本機子專案。為此，我們使用 project(…​) 符號。在我們的範例中，utilities 函式庫需要 list 函式庫。而 app 使用 utilities 函式庫。如果本機專案相互依賴，Gradle 會在需要時（且僅在需要時）負責建置相依專案。若要深入了解，請參閱有關 Gradle 中相依性管理 的文件。

  • 第三，外掛可能有一個或多個組態區塊。如果它們針對一個專案設定特定內容，才應該直接在建置指令碼中使用這些區塊。否則，此類組態也屬於慣例外掛。在此範例中，我們使用 application {} 區塊，這是 application 外掛的特定區塊，將 app 專案中的 mainClass 設定為 demo.app.App (1)。

我們擁有的最後一個建置檔案是 buildSrc 中的 build.gradle(.kts) 檔案。

buildSrc/build.gradle.kts
plugins {
    `kotlin-dsl` (1)
}

repositories {
    gradlePluginPortal() (2)
}
buildSrc/build.gradle
plugins {
    id 'groovy-gradle-plugin' (1)
}

repositories {
    gradlePluginPortal() (2)
}

此檔案設定階段以建置慣例外掛本身。透過套用外掛開發的其中一個外掛 — groovy-gradle-plugin 或 kotlin-dsl — (1) 我們啟用支援，將慣例外掛寫為 buildSrc 中的建置檔案。這就是我們在上面已經檢查過的慣例外掛。此外，我們將 Gradle 的外掛入口網站新增為儲存庫 (2)，這讓我們可以存取社群外掛。若要使用外掛，需要在 dependencies {} 區塊中將其宣告為相依性。

除了 Gradle 建置檔案之外，您可以在對應的資料夾中找到範例 Groovy 原始碼和測試原始碼。請隨時修改這些產生的原始碼和測試，以探索 Gradle 在執行建置時如何對變更做出反應，如下所述。

執行測試

您可以使用 ./gradlew check 執行所有子專案中的所有測試。當您使用純粹的任務名稱（例如 check）呼叫 Gradle 時，將會針對提供該任務的所有子專案執行該任務。若要僅針對特定子專案，可以使用任務的完整路徑。例如，:app:check 將僅執行 app 專案的測試。然而，在這個範例中，其他子專案仍會編譯，因為 app 對它們宣告相依性。

$ ./gradlew check

BUILD SUCCESSFUL
9 actionable tasks: 9 executed

如果所有測試都順利通過，Gradle 就不會在主控台中列印更多輸出。您可以在 <subproject>/build/reports 資料夾中找到測試報告。請隨時變更部分範例程式碼或測試，並重新執行 check 以了解如果測試失敗會發生什麼事。

執行應用程式

感謝 application 外掛程式，您可以直接從命令列執行應用程式。run 任務會指示 Gradle 執行指定給 mainClass 屬性的類別中的 main 方法。

$ ./gradlew run

> Task :app:run
Hello world!

BUILD SUCCESSFUL
2 actionable tasks: 2 executed
您第一次執行包裝腳本 gradlew 時，可能會延遲，因為 gradle 的那個版本會下載並儲存在您本地的 ~/.gradle/wrapper/dists 資料夾中。

打包應用程式

application 外掛程式也會為您打包應用程式，包含其所有相依性。封存檔中也會包含一個腳本，讓您可以使用單一指令啟動應用程式。

$ ./gradlew build

BUILD SUCCESSFUL in 0s
7 actionable tasks: 7 executed

如果您執行如上所示的完整建置，Gradle 會為您製作兩種格式的封存檔：app/build/distributions/app.tar 和 app/build/distributions/app.zip。

發佈建置掃描

進一步了解建置在幕後執行的最佳方式，就是發佈 建置掃描。要執行此動作，請使用 --scan 旗標執行 Gradle。

$ ./gradlew build --scan

BUILD SUCCESSFUL in 0s
7 actionable tasks: 7 executed

Publishing a build scan to scans.gradle.com requires accepting the Gradle Terms of Service defined at https://gradle.com/terms-of-service.
Do you accept these terms? [yes, no] yes

Gradle Terms of Service accepted.

Publishing build scan...
https://gradle.com/s/5u4w3gxeurtd2

按一下連結，探索已執行的任務、已下載的相依性，以及更多詳細資訊！

摘要

完成了！您現在已成功使用 Gradle 設定和建置 Groovy 應用程式專案。您已學會如何

  • 初始化產生 Groovy 應用程式的專案

  • 透過結合多個子專案來建立模組化軟體專案

  • 使用 buildSrc 中的慣例外掛程式，在子專案間共用建置設定邏輯

  • 在所有子專案中執行名稱類似的任務

  • 在特定子專案中執行任務

  • 建置、打包和執行應用程式

後續步驟

當您的專案成長時，您可能會對如何設定 JVM 專案、建構多專案建置和相依性管理有興趣