Gradle 8.14 发布说明 - Gradle 构建系统

Gradle 8.14 引入了延迟依赖配置初始化，以提高配置性能和内存使用率。Problems API 进行了扩展，以支持任意结构化数据，使得 IDE 通过 Tooling API 消费丰富的诊断信息更加容易。

此外，配置缓存包含一个新的完整性检查模式，用于改进调试。

升级说明

通过更新项目中的 Wrapper，将你的构建切换到使用 Gradle 8.14

./gradlew wrapper --gradle-version=8.14 && ./gradlew wrapper

请参阅 Gradle 8.x 升级指南，了解升级到 Gradle 8.14 时的废弃项、重大更改和其他注意事项。

有关 Java、Groovy、Kotlin 和 Android 的兼容性信息，请参阅完整兼容性说明。

新特性和可用性改进

支持 Java 24

通过此版本，Gradle 支持 Java 24。这意味着除了用于工具链之外，你现在还可以将 Java 24 用于 daemon。

第三方工具与 Java 24 的兼容性可能仍然有限。如果你正在使用 Tooling API，由于它使用 JNI，你需要在启动时启用原生访问。详情请参阅 JEP 472。

更多详情请参阅兼容性文档。

GraalVM Native Image 工具链选择

Gradle 的工具链支持允许为项目构建（编译代码、运行测试，甚至运行 Gradle 本身）提供和选择特定的 JDK 版本。

通过此版本，工具链选择已扩展到支持 GraalVM Native Image 功能。

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
        nativeImageCapable = true
    }
}

这使得 Gradle 在解析工具链时可以仅选择支持 Native Image 的 JDK。更多详情请参阅工具链文档。

注意：daemon 工具链也支持 Native Image 功能选择。

跳过的测试现在报告假设违例

当测试因假设违例而被跳过时，Gradle 现在会在 HTML 和 JUnit XML 报告中都包含原因。这适用于 JUnit 4、JUnit Platform 和 TestNG。例如，JUnit Platform 提供了一个 Assumptions API 来有条件地跳过测试。

package org.example;

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assumptions.*;

class LibraryTest {
    @Test 
    void someLibraryMethodReturnsTrue() {
        assumeTrue(canExecute(), "missing requirements to run this test");
        // Code for the rest of the test
    }   
}

如果 assumeTrue 检查失败，原因（“缺少运行此测试的要求”）现在在 XML 和 HTML 测试报告中可见。

HTML test report check

此功能由 Ivy Chen 和 Aurimas Liutikas 贡献。

构建编写改进

Gradle 提供丰富的 API，供插件作者和构建工程师开发自定义构建逻辑。

配置延迟初始化

就像任务一样，依赖配置现在仅在必要时才会被实例化。

从此版本开始，应用 base 插件——无论是直接应用还是通过其他插件（如 Java 或 Kotlin 插件）应用——不再实例化所有使用 register 方法或孵化中的基于角色的工厂方法（如 configurations.resolvable(...)）声明的配置。

此更改可以减少某些构建的配置时间并降低内存使用。

为了利用此改进，请确保在声明配置时使用 register 方法而不是 create。

configurations {
    // Eager: this configuration is realized immediately
    create("myEagerConfiguration")

    // Lazy: this configuration is only realized when needed
    register("myLazyConfiguration")
}

Problems API 扩展支持任意数据

Gradle 8.13 在 Problems API 中引入了对附加数据的支持，允许用户为报告的问题附加额外上下文——尽管存在一些限制。

此版本消除了这些限制。你现在可以在问题报告中包含任何任意数据。

此增强功能对于同时管理插件及其通过 Tooling API 集成的 IDE 实现者来说尤其有价值，因为在此场景下，传达丰富、结构化的诊断信息至关重要。

例如，自定义 worker 任务可以报告问题并附加详细的附加数据——包括基本类型字段、列表和复合对象。

public abstract class ProblemWorkerTask implements WorkAction<ProblemsWorkerTaskParameter> {

    // Use the Problems interface to report problems
    @Inject
    public abstract Problems getProblems();

    // Use the ObjectFactory to create instances of classes for composition
    @Inject
    public abstract ObjectFactory getObjectFactory();

    @Override
    public void execute() {
        ProblemId problemId = ProblemId.create("type", "label", ProblemGroup.create("generic", "Generic"));
        getProblems().getReporter().report(problemId, problem -> problem
            .additionalData(SomeData.class, dataInstance -> {
                // Provider API properties can be used as arbitrary data
                dataInstance.getSome().set("some");
                // Getters and setters can be used as arbitrary data
                dataInstance.setName("someData");
                // Collections can be used as arbitrary data
                dataInstance.setNames(Collections.singletonList("someMoreData"));
                
                SomeOtherData compositionDataInstance = getObjectFactory().newInstance(SomeOtherData.class);
                compositionDataInstance.setOtherName("otherName");
                
                // Composition can be used as arbitrary data
                dataInstance.setOtherData(compositionDataInstance);
            })
        );
    }
}

附加到问题的数据使用 plain interface 进行建模，并在适用时使用 Gradle 类型。

import org.gradle.api.problems.AdditionalData;
import org.gradle.api.provider.Property;
import java.util.List;

public interface SomeData extends AdditionalData {
    Property<String> getSome();

    String getName();
    void setName(String name);

    List<String> getNames();
    void setNames(List<String> names);

    SomeOtherData getOtherData();
    void setOtherData(SomeOtherData otherData);
}

public interface SomeOtherData {
    String getOtherName();
    void setOtherName(String name);
}

通过此增强功能，Problems API 成为一个更强大的诊断工具——能够在构建、IDE 和 Tooling API 层中传递丰富、结构化和类型化的上下文。

通过 Tooling API 接收附加数据

Tooling API (TAPI) 中的新方法 CustomAdditionalData.get() 允许消费者检索与 Gradle 构建期间报告的构建问题（或其他事件）相关的附加数据。

以前，Tooling API 的消费者在检查问题或构建事件时只能访问一组固定的预定义字段。通过此新方法，Gradle 可以在构建期间序列化丰富、结构化的数据，并将其作为类型安全的视图接口暴露给 Tooling API。

在接收端，你可以像这样访问此数据：

void someMethod(List<Problem> problems) {
    SomeDataView view = problems.get(0).getAdditionalData().get(SomeDataView.class);
    
    System.out.println(view.getName());
    System.out.println(view.getNames().get(0));
    System.out.println(view.getOtherData().getOtherName());
}

这些视图接口反映了构建逻辑生成的数据结构。

interface SomeOtherDataView {
    String getOtherName();
}

interface SomeDataView {
    String getSome();

    String getName();

    List<String> getNames();

    SomeOtherDataView getOtherData();
}

这些类型提供了一种安全、结构化的方式，可以在 IDE 或其他基于 TAPI 的工具中消费自定义数据，而无需依赖脆弱的解析或对内部数据格式的假设。

配置缓存改进

配置缓存通过缓存配置阶段的结果并在后续构建中重用它来缩短构建时间。此功能可以显著提高构建性能。

完整性检查模式

为了帮助诊断隐晦的配置缓存加载错误，你现在可以使用 org.gradle.configuration-cache.integrity-check 属性启用更严格的完整性检查。

此模式提供更详细的错误消息，以精确指出构建中序列化失败的部分。

例如，你可能不再看到像这样晦涩难懂的错误：

Index 4 out of bounds for length 3

而现在可能看到：

Configuration cache state could not be cached: field `user` of task `:greet` of type `GreetTask`: The value cannot be decoded properly with 'JavaObjectSerializationCodec'. It may have been written incorrectly or its data is corrupted.

注意：启用完整性检查会增加配置缓存的大小并减慢缓存读写速度。仅用于故障排除，不要在常规构建中使用。

Gradle 发布说明

目录