Gradle

Gradle 是用於 JVM 專案及許多其他生態系統的建置自動化工具。 建置邏輯使用 Groovy DSL（.gradle）或 Kotlin DSL （.gradle.kts）撰寫。Gradle 本身執行於 JVM 上。

專案檔案 #

在儲存庫根目錄中，重要檔案包括：

• settings.gradle[.kts] 定義建置並納入子專案。 多專案建置必須包含此檔案，也可以使用它設定根專案名稱。
• build.gradle[.kts] 為根專案或子專案定義外掛程式、相依性、工作和慣例。
• gradle.properties 儲存專案屬性。使用者層級的屬性可以位於 ~/.gradle/gradle.properties。
• gradlew、gradlew.bat 和 gradle/wrapper/ 構成 Gradle Wrapper， 應提交至版本控制。
• .gradle/ 是本機 Gradle 狀態目錄，應將其加入忽略清單。

在 settings.gradle.kts 中使用 include("service", "web") 註冊 子專案。每個子專案可以擁有自己的建置指令碼，同時共用整個儲存庫的慣例。

使用 Wrapper #

在 CI 和日常開發中，應執行 ./gradlew build，而不是全域安裝的 gradle。Wrapper 會下載 gradle/wrapper/gradle-wrapper.properties 中指定的版本，使建置具備可重現性。 應審查 Wrapper 升級，並在發行版檢查碼可用時驗證該檢查碼。

常用命令包括：

./gradlew tasks
./gradlew test
./gradlew build
./gradlew clean
./gradlew :service:test

相依性與工作 #

外掛程式會新增組態和工作。例如，Java 外掛程式提供 implementation、api（使用 java-library 時）、compileOnly、runtimeOnly 以及測試組態。應優先使用範圍最窄的組態：implementation 相依性不會自動成為 使用者編譯類別路徑的一部分，而 API 相依性會成為該公開契約的一部分。

Gradle 會執行工作圖。工作應宣告其輸入和輸出，讓增量建置和建置快取能安全地略過 已完成的工作。在組態階段應避免執行未宣告的檔案或網路操作；應改用延遲 Provider 和工作動作。

使用版本目錄、平台或相依性限制集中管理版本。在可重現性很重要時，鎖定重要相依性的版本， 並且不要將認證資訊提交至 gradle.properties；應透過環境變數、安全的 CI 密鑰存放區或 被忽略的本機檔案提供認證資訊。