Tooling 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 项目并运行 Task。
IntelliJ IDEA 使用 Tooling API 来导入您的 Gradle 项目并运行 Task。

Tooling API 功能

Tooling API 的一个基本特征是它以版本独立的方式运行。这意味着您可以使用相同的 API 来处理使用不同 Gradle 版本的构建，包括比您正在使用的 Tooling API 版本更新或更旧的版本。Tooling API 了解 Gradle wrapper，并且默认情况下，使用与 wrapper 驱动的构建所使用的 Gradle 版本相同的版本。

Tooling API 提供的一些功能

查询构建的详细信息，包括项目层次结构和项目依赖项、外部依赖项（包括源和 Javadoc jar）、源目录和每个项目的 Task。
执行构建并监听 stdout 和 stderr 日志记录以及进度消息（例如，在命令行运行时在“状态栏”中显示的消息）。
执行特定的测试类或测试方法。
在构建执行时接收有趣的事件，例如项目配置、Task 执行或测试执行。
取消正在运行的构建。
将多个独立的 Gradle 构建组合成一个复合构建。
Tooling API 可以下载并安装适当的 Gradle 版本，类似于 wrapper。
该实现是轻量级的，只有少量依赖项。它也是一个行为良好的库，并且不对您的类加载器结构或日志配置进行任何假设。这使得 API 易于嵌入到您的应用程序中。

Tooling API 和 Gradle 构建守护进程

Tooling API 始终使用 Gradle 守护进程。这意味着后续对 Tooling API 的调用，无论是模型构建请求还是 Task 执行请求，都将在同一个长期运行的进程中执行。Gradle 守护进程包含有关守护进程的更多详细信息，特别是关于何时派生新守护进程的情况的信息。

快速入门

由于 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 项目。使用此连接，您可以执行 Task、测试和检索与此项目相关的模型。

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 不兼容。

此页是否对您有帮助？