Gradle 正在持续开发中。新版本会定期频繁发布(大约每六周一次),如关于生命周期结束支持的章节所述。

持续改进与频繁发布相结合,使得新功能能够尽早提供给用户。早期用户提供了宝贵的反馈,这些反馈被纳入开发过程。

定期向用户提供新功能是 Gradle 平台的核心价值。

同时,API 和功能的稳定性受到高度重视,并被视为 Gradle 平台的核心价值。关于向后兼容性的章节将设计选择和自动化测试纳入开发过程并进行规范化。

Gradle 的特性生命周期旨在实现这些目标。它还向 Gradle 用户传达了一个特性的状态。在此上下文中,术语特性通常指 API 或 DSL 方法或属性,但它不局限于此定义。命令行参数和执行模式(例如构建守护进程)是其他特性的两个示例。

特性状态

特性可以处于以下四种状态之一

1. 内部 (Internal)

内部特性并非设计用于公共使用,仅供 Gradle 自身使用。它们可能在任何时间点以任何方式改变,恕不另行通知。因此,我们建议避免使用此类特性。内部特性没有文档。如果它出现在本用户手册、DSL 参考或 API 参考中,那么该特性就不是内部的。

内部特性可能会演变为公共特性。

2. 孵化中 (Incubating)

特性以孵化中状态引入,以便在公开之前将实际反馈纳入其中。它还允许愿意测试潜在未来变化的用户提前访问。

处于孵化中状态的特性可能会在未来的 Gradle 版本中发生变化,直到它不再是孵化中状态。Gradle 版本中对孵化中特性的更改将在该版本的发行说明中突出显示。新特性的孵化期因特性的范围、复杂性和性质而异。

处于孵化中的特性会被标记。在源代码中,所有孵化中的方法/属性/类都使用incubating注解。这导致它们在 DSL 和 API 参考中有一个特殊标记。

如果本用户手册中讨论了孵化中的特性,则会明确说明它处于孵化中状态。

特性预览 API

特性预览 API 允许通过在您的settings文件中添加 enableFeaturePreview('FEATURE') 来激活某些孵化中的特性。个别预览特性将在发行说明中公布。

孵化中的特性被提升为公开或被移除时,它们的特性预览标志将过时,不起作用,应从 settings 文件中移除。

3. 公开 (Public)

非内部特性的默认状态是公开。用户手册、DSL 参考或 API 参考中记录的任何未明确说明为孵化中废弃的都被视为公开。特性被称之为从孵化中状态提升公开状态。每个版本的发行说明都指出该版本提升了哪些之前处于孵化中的特性。

一个公开的特性永远不会在不经历废弃的情况下被移除或故意更改。所有公共特性都受向后兼容性策略的约束。

4. 废弃 (Deprecated)

由于 Gradle 的自然演变,一些特性可能会被替换或变得不相关。这些特性在被废弃后最终将从 Gradle 中移除。一个废弃的特性可能会停滞,直到最终根据向后兼容性策略被移除。

废弃的特性会显示出来。在源代码中,所有废弃的方法/属性/类都使用“@java.lang.Deprecated”注解,这反映在 DSL 和 API 参考中。在大多数情况下,废弃的元素有替代方案,这将在文档中描述。使用废弃特性会在 Gradle 的输出中产生运行时警告。

应避免使用废弃特性。每个版本的发行说明都指出该版本正在废弃的任何特性。

向后兼容性策略

Gradle 提供跨主要版本(例如 1.x2.x 等)的向后兼容性。一旦一个公共特性在 Gradle 版本中引入,它将无限期地保留,除非被废弃。一旦废弃,它可能会在下一个主要版本中移除。废弃的特性可能会在主要版本之间得到支持,但这不是保证。

版本生命周期结束策略

每天都会创建一个新的 Gradle 每夜构建版本。

这包含当天通过 Gradle 广泛的持续集成测试所做的所有更改。每夜构建版本可能包含新的更改,这些更改可能稳定也可能不稳定。

Gradle 团队为每个次要或主要版本创建预发布分发版,称为发布候选版 (RC)。在短时间(通常一周)内未发现问题后,发布候选版将被提升为通用可用 (GA) 版本。如果在发布候选版中发现回归,则会创建新的 RC 分发版,并重复该过程。发布候选版在发布窗口打开期间受支持,但它们不适用于生产环境。在 RC 阶段非常感谢错误报告。

由于关键错误修复或回归,Gradle 团队可能会创建额外的补丁版本来替换最终版本。例如,Gradle 5.2.1 替换了 Gradle 5.2 版本。

一旦发布候选版发布,所有特性开发都将转移到下一个主要版本的下一个版本。因此,每个 Gradle 次要版本都会导致同一主要版本中的先前次要版本达到生命周期结束 (EOL)。EOL 版本不接收错误修复或特性回溯。

对于主要版本,Gradle 将关键修复和安全修复回溯到前一个主要版本中的最后一个次要版本。例如,当 Gradle 7 是最新的主要版本时,6.x 系列中发布了几个版本,包括 Gradle 6.9(以及后续版本)。

因此,每个 Gradle 主要版本都会导致

  • 上一个主要版本变为仅维护状态。它将只接收关键错误修复和安全修复。

  • 上一个主要版本之前的主要版本变为生命周期结束 (EOL),并且该发布系列将不再接收任何新修复。

公共 Gradle API

Gradle 提供了许多公共 API,允许开发人员与各种构建系统组件进行交互。

任何包含 Internal 的类名,或位于包含 .internal. 段的包中的类名,根据定义不属于公共 Gradle API,不应依赖其进行稳定使用。

下表总结了公共 Gradle API 及其常见用例。这不是一个详尽的列表

API 包 描述 常见用例

org.gradle.api

核心 Gradle API

- 定义了 ProjectTaskPlugin 等关键接口
- 用于配置项目和任务

org.gradle.authentication

认证 API

- 处理仓库和服务的认证
- 支持用户名/密码、OAuth 和其他机制

org.gradle.build

构建生命周期 API

- 管理构建阶段和执行
- 用于控制任务的顺序

org.gradle.buildinit

构建初始化 API

- 用于生成新的 Gradle 项目
- 支持引导各种项目类型

org.gradle.caching

构建缓存 API

- 提供了存储和重用构建输出的机制
- 用于增量构建和 CI 优化

org.gradle.concurrent

并发执行 API

- 管理并行任务执行
- 有助于优化 Gradle 构建性能

org.gradle.deployment

部署 API

- 支持管理和自动化应用程序部署
- 适用于 CI/CD 流水线

org.gradle.env

环境配置 API

- 提供对环境变量和设置的访问
- 用于根据外部条件配置构建

org.gradle.external.javadoc

Javadoc API

- 为外部依赖项生成 Javadoc
- 用于 Java 文档工作流

org.gradle.ide

IDE 集成 API

- 管理 Gradle 对 IntelliJ 和 Eclipse 等 IDE 的支持
- 配置 IDE 项目设置

org.gradle.includedbuild

复合构建 API

- 实现了跨多个 Gradle 构建的依赖管理
- 支持模块化开发

org.gradle.ivy

Ivy 依赖管理 API

- 支持 Ivy 仓库和依赖解析
- Maven 的替代品,用于依赖管理

org.gradle.jvm

Java 虚拟机 API

- 管理基于 JVM 的构建
- 包括工具链和 JDK 选择

org.gradle.language

语言插件 API

- 定义 Gradle 对多种语言(Java、Kotlin 等)的支持
- 用于多语言项目

org.gradle.maven

Maven 依赖管理 API

- 支持 Maven 仓库和依赖解析
- 常用于 Java 项目

org.gradle.nativeplatform

原生平台 API

- 提供对 C、C++ 和其他原生构建的支持
- 用于跨平台开发

org.gradle.normalization

输入规范化 API

- 通过定义输入规范化规则来优化缓存
- 有助于改进增量构建

org.gradle.platform

平台依赖管理 API

- 定义和管理平台的依赖约束
- 适用于多模块项目

org.gradle.play

Play 框架支持 API

- 提供对 Play 框架项目的支持
- 用于 Web 应用程序开发

org.gradle.plugin.devel

插件开发 API

- 支持编写和发布自定义 Gradle 插件
- 供插件作者使用

org.gradle.plugin.repository

插件仓库 API

- 定义 Gradle 插件的仓库
- 用于从 Gradle 插件门户获取插件

org.gradle.plugin.use

插件应用 API

- 处理构建脚本中的插件应用
- 简化了 plugins {} 块的插件使用

org.gradle.plugin.management

插件管理 API

- 为 Gradle 插件提供集中管理
- 有助于配置插件版本和仓库

org.gradle.plugins

内置插件 API

- 包括 Gradle 的内置插件(Java、Kotlin 等)
- 用于应用标准构建逻辑

org.gradle.process

进程管理 API

- 允许从 Gradle 任务运行外部进程
- 适用于自动化和脚本执行

org.gradle.testfixtures

测试夹具 API

- 为 Gradle 插件开发人员提供测试工具
- 有助于测试 Gradle 任务和插件

org.gradle.testing.jacoco

JaCoCo 测试覆盖率 API

- 与 JaCoCo 集成以生成代码覆盖率报告
- 用于跟踪 Java 项目中的测试覆盖率

org.gradle.tooling

Tooling API (TAPI)

- 允许外部应用程序与 Gradle 交互
- 由 IDE 和 CI 系统用于运行 Gradle 构建

org.gradle.swiftpm

Swift 包管理器 API

- 提供 Gradle 与 Swift 包管理器的集成
- 用于管理 Swift 依赖项

org.gradle.model

基于模型规则的 API

- 用于使用模型配置 Gradle 构建的旧版 API
- 已被现代 Gradle DSL 取代

org.gradle.testkit

Gradle TestKit API

- 提供用于测试 Gradle 插件的实用程序
- 用于编写 Gradle 插件的功能测试

org.gradle.testing

测试框架 API

- 定义 Gradle 构建的测试框架
- 支持 JUnit、TestNG 和 Spock

org.gradle.vcs

版本控制系统 API

- 允许从 VCS(Git、SVN)获取依赖项
- 用于管理基于源代码的依赖项

org.gradle.work

工作执行 API

- 提供用于并行和增量任务执行的实用程序
- 有助于优化长时间运行的 Gradle 任务

org.gradle.workers

Worker API

- 实现了 Gradle 任务的并行执行
- 用于在工作线程中运行任务

org.gradle.util

实用工具 API

- 提供 Gradle 内部使用的各种实用函数
- 用于 Gradle 构建逻辑和插件开发