工具 API - Gradle 建構系統

使用 Tooling API 嵌入 Gradle

Tooling API 簡介

Gradle 提供了一個稱為 Tooling API 的程式化 API，您可以使用它將 Gradle 嵌入到您自己的軟體中。這個 API 讓您可以執行和監控建置，並查詢 Gradle 關於建置的詳細資訊。這個 API 的主要受眾是 IDE、CI 伺服器、其他 UI 作者；然而，這個 API 開放給任何需要在其應用程式中嵌入 Gradle 的人。

Gradle TestKit 使用 Tooling API 來對您的 Gradle 插件進行功能測試。
Eclipse Buildship 使用 Tooling API 來匯入您的 Gradle 專案並執行任務。
IntelliJ IDEA 使用 Tooling API 來匯入您的 Gradle 專案並執行任務。

Tooling API 功能

Tooling API 的一個基本特性是它以版本獨立的方式運作。這表示您可以使用相同的 API 來處理使用不同 Gradle 版本的建置，包括比您使用的 Tooling API 版本更新或更舊的版本。Tooling API 具有 Gradle Wrapper 感知能力，並且預設情況下，使用與 Wrapper 驅動的建置相同的 Gradle 版本。

Tooling API 提供的一些功能

查詢建置的詳細資訊，包括專案階層和專案依賴關係、外部依賴關係（包括原始碼和 Javadoc jar 檔）、原始碼目錄以及每個專案的任務。
執行建置並監聽 stdout 和 stderr 日誌記錄和進度訊息（例如，當您在命令列上執行時，在「狀態列」中顯示的訊息）。
執行特定的測試類別或測試方法。
在建置執行時接收有趣的事件，例如專案配置、任務執行或測試執行。
取消正在執行的建置。
將多個獨立的 Gradle 建置組合到單一複合建置中。
Tooling API 可以下載並安裝適當的 Gradle 版本，類似於 Wrapper。
實作是輕量級的，只有少數依賴項目。它也是一個行為良好的程式庫，並且不對您的類別載入器結構或日誌記錄配置做任何假設。這使得 API 易於嵌入到您的應用程式中。

Tooling API 和 Gradle 建置守護進程

Tooling API 始終使用 Gradle 守護進程。這表示後續對 Tooling API 的呼叫，無論是模型建置請求還是任務執行請求，都將在相同的長生命週期進程中執行。Gradle Daemon 包含有關守護進程的更多詳細資訊，特別是有關何時 fork 新守護進程的情況。

快速開始

由於 Tooling API 是開發人員的介面，因此 Javadoc 是其主要文件。

若要使用 Tooling API，請將以下儲存庫和依賴關係宣告新增至您的建置腳本

build.gradle.kts

repositories {
    maven { url = uri("https://repo.gradle.org/gradle/libs-releases") }
}

dependencies {
    implementation("org.gradle:gradle-tooling-api:$toolingApiVersion")
    // The tooling API need an SLF4J implementation available at runtime, replace this with any other implementation
    runtimeOnly("org.slf4j:slf4j-simple:1.7.10")
}

build.gradle

repositories {
    maven { url = 'https://repo.gradle.org/gradle/libs-releases' }
}

dependencies {
    implementation "org.gradle:gradle-tooling-api:$toolingApiVersion"
    // The tooling API need an SLF4J implementation available at runtime, replace this with any other implementation
    runtimeOnly 'org.slf4j:slf4j-simple:1.7.10'
}

Tooling API 的主要進入點是 GradleConnector。您可以從那裡導航以尋找程式碼範例並探索可用的 Tooling API 模型。您可以使用 GradleConnector.connect() 來建立 ProjectConnection。ProjectConnection 連接到單一 Gradle 專案。使用此連線，您可以執行任務、測試並檢索與此專案相關的模型。

Java 和 Gradle 版本相容性

實作 Gradle 整合時，應考慮以下組件：Tooling API 版本、執行 Tooling API 用戶端的 JVM（即 IDE 進程）、執行 Gradle 守護進程的 JVM 以及 Gradle 版本。

Tooling API 本身是一個 Java 程式庫，作為 Gradle 發行版本的一部分發布。每個 Gradle 發行版本都有一個對應的 Tooling API 版本，版本號碼相同。

Tooling API 類別會載入到用戶端的 JVM 中，因此它們應該具有相符的版本。目前版本的 Tooling API 程式庫是使用 Java 8 相容性編譯的。

執行 Tooling API 用戶端的 JVM 和執行守護進程的 JVM 可以不同。同時，透過自訂建置動作傳送到建置的類別需要以最低支援的 Java 版本為目標。Gradle 支援的 JVM 版本是版本特定的。上限在相容性矩陣中定義。下限的規則如下：

Gradle 3.x 和 4.x 需要 Java 7 的最低版本。
Gradle 5 及更高版本需要 Java 8 的最低版本。

Tooling API 版本保證支援使用過去五個主要發行版本的所有 Gradle 版本執行建置。例如，Tooling API 8.0 發行版本與 Gradle 版本 >= 3.0 相容。此外，Tooling API 保證與目前和下一個主要版本的未來 Gradle 發行版本相容。這表示，例如，Tooling API 的 8.1 版本將能夠執行 Gradle 9.x 建置，並且可能與 Gradle 10.0 不相容。

這個頁面有幫助嗎？