工具 API - Gradle 构建系统

使用 Tooling API 嵌入 Gradle

Tooling API 简介

Gradle 提供了一个名为 Tooling 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）、源目录以及每个项目的任务。
执行构建并监听标准输出和标准错误日志记录以及进度消息（例如，在命令行上运行时“状态栏”中显示的消息）。
执行特定的测试类或测试方法。
在构建执行时接收有趣的事件，例如项目配置、任务执行或测试执行。
取消正在运行的构建。
将多个独立的 Gradle 构建组合成一个复合构建。
Tooling API 可以下载和安装适当的 Gradle 版本，类似于 wrapper。
该实现是轻量级的，只有少量依赖项。它也是一个行为良好的库，并且不对您的类加载器结构或日志记录配置做任何假设。这使得该 API 易于嵌入到您的应用程序中。

Tooling API 和 Gradle 构建守护进程

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

快速入门

由于 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:2.0.17")
}

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:2.0.17'
}

Tooling API 的主要入口点是 GradleConnector。您可以从那里导航以查找代码示例并探索可用的 Tooling API 模型。您可以使用 GradleConnector.connect() 创建一个 ProjectConnection。一个 ProjectConnection 连接到一个 Gradle 项目。使用该连接，您可以执行任务、测试并检索与此项目相关的模型。

Java 和 Gradle 版本的兼容性

在实现 Gradle 集成时应考虑以下组件：Tooling API 版本、运行 Tooling API 客户端的 JVM（即 IDE 进程）、运行 Gradle 守护进程的 JVM 和 Gradle 版本。

Tooling API 本身是作为 Gradle 发布的一部分发布的 Java 库。每个 Gradle 发布都有一个对应相同版本号的 Tooling API 版本。

Tooling API 类加载到客户端的 JVM 中，因此它们应该具有匹配的版本。当前版本的 Tooling API 库是使用 Java 8 兼容性编译的。

运行 Tooling API 客户端的 JVM 和运行守护进程的 JVM 可以不同。同时，通过自定义构建操作发送到构建的类需要针对支持的最低 Java 版本。Gradle 支持的 JVM 版本是特定于版本的。上限在兼容性矩阵中定义。下限规则如下

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

Tooling API 版本保证支持运行最近五个主要版本的所有 Gradle 版本。例如，Tooling API 9.0 版本与 Gradle 版本 >= 4.0 兼容。此外，Tooling API 保证与当前和下一个主要版本的未来 Gradle 版本兼容。这意味着，例如，Tooling API 的 8.1 版本将能够运行 Gradle 9.x 构建，并且*可能*在 Gradle 10 中出现问题。

此页面有帮助吗？