Gradle学习 - 技术栈

https://docs.gradle.org.cn/current/userguide/installation.html#installation

学习参考如上官网教程

Gradle 安装

如果只是想运行现有的 Gradle 项目，并且构建使用了 Gradle Wrapper，就不需要安装 Gradle。可以根据项目根目录下面有没有 gradlew 或 gradlew.bat 文件来识别。如果有，代表不需要安装。

使用 IDEA 创建的 Spring Boot4 项目，用 Gradle 构建，项目目录下是有这两个文件的，所以我们就不手动安装了

并且大多数项目不使用已安装的 Gradle 版本，而是用 Gradle Wrapper，并且目前推荐也是使用 Gradle Wrapper。

先决条件

无论安不安装，都需要满足先决条件，Gradle 需要在 JDK17 以上才能运行

入门

基础知识

核心概念

项目结构

bash 复制代码

project
├── gradle                          1
│   ├── libs.versions.toml              2
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew                         3
├── gradlew.bat                         3
├── settings.gradle(.kts)           4
├── subproject-a
│   ├── build.gradle(.kts)              5
│   └── src                         6
└── subproject-b
    ├── build.gradle(.kts)             5
    └── src                         6

用于存储 wrapper 文件等的 Gradle 目录
用于依赖管理的 Gradle 版本目录
Gradle wrapper 脚本 - 这是一个 Gradle 项目！
Gradle 设置文件，用于定义根项目名称和子项目
两个子项目 subproject-a 和 subproject-b 的 Gradle 构建脚本
项目的源代码和/或附加文件

调用 Gradle

使用 Gradle Wrapper

wrapper 是一个调用声明的 Gradle 版本的脚步，是执行 Gradle 构建的推荐方式

bash 复制代码

$ ./gradlew build

Wrapper 基础

wrapper 脚本会调用一个声明的 Gradle 版本，如果需要，会提前下载。

wrapper 脚本就是那两个文件 gradlew 和 gradlew.bat，如果项目里面没有这两个，那说明你很可能不是 Gradle 项目，或者 wrapper 还没设置。

wrapper 的好处就是

自动下载并使用特定的 Gradle 版本
不同的用户和环境提供相同的 Gradle 版本
无需手动安装 Gradle 就可以运行 Gradle 构建

❓ gradlew 和 gradlew.bat 什么区别？

第一个是 Shell 脚本，专门给 macOS 和 Linux 用户用的，第二个是 Windows 批处理文件，专门给 Windows 用户用的。这是为了保证不同系统在使用的时候可以使用到相同版本的 Gradle。其实本质上一台机器上只可能用到一个。

使用 Gradle Wrapper

在 Linux 或 macOS 上

bash 复制代码

$ ./gradlew build

在 Windows PowerShell 上

bash 复制代码

$ gradlew.bat build

看看正常项目编译后会有啥

理解 wrapper 文件

bash 复制代码

.
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar  1
│       └── gradle-wrapper.properties   2
├── gradlew 3
└── gradlew.bat 4

gradle-wrapper.jar: 这是一个小的 JAR 文件，包含 Gradle Wrapper 代码。它负责为项目下载和安装正确版本的 Gradle（如果尚未安装）。
gradle-wrapper.properties: 此文件包含 Gradle Wrapper 的配置属性，例如分发 URL（从哪里下载 Gradle）和分发类型（ZIP 或 TARBALL）。
gradlew: 这是一个 shell 脚本（基于 Unix 的系统），作为 gradle-wrapper.jar 的包装器。它用于在基于 Unix 的系统上执行 Gradle 任务，而无需手动安装 Gradle。
gradlew.bat: 这是一个批处理脚本（Windows），其用途与 gradlew 相同，但用于 Windows 系统。

官网说我们不应该去更改这些文件。

但是我看 gradle-wrapper.properties 里面有个属性 distributionUrl，这个是设置仓库的 url，就是我们去哪里下载，我们可以用镜像加速
properties 复制代码
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-9.4.1-bin.zip

这个上面就包含了咱们 gradle 的版本信息 Gradle 9.4.1

如果想查看版本信息，可以通过命令

bash 复制代码

$ ./gradlew --version # Linux
$ gradlew.bat --version

如果想更新 Gradle 版本怎么做？通过命令

bash 复制代码

$ ./gradlew wrapper --gradle-version 7.2 # 后面是版本号

如果你执行了这个命令，你会发现它把 gradle-wrapper.properties 里面的内容都改了，也就是 distributionUrl 对应后面的版本。所以想改版本也可以手动改这个。

CLI 基础

可以通过命令行与 Gradle 交互，可以用它来运行任务、检查构建、管理依赖项和控制日志记录，所有这些都通过灵活而强大的命令行选项实现。

运行命令

结构大致如下

bash 复制代码

gradle [taskName...] [--option-name...]

可以指定多个任务，中间用空格分割

bash 复制代码

gradle clean build

命令行选项

Gradle 命令可以包含各种选项来调整其行为。对于接受值的选项，可以使用等号来提高清晰度

bash 复制代码

gradle [...] --console=plain

有的选项是切换开关，比如启用或禁用构建缓存

bash 复制代码

gradle build --build-cache
gradle build --no-build-cache

执行任务

在 Gradle 中，任务属于特定的项目。为了清楚地指明要运行哪个任务，尤其是在多项目构建中，使用冒号（:）作为项目分隔符。

要在根项目级别执行名为 test 的任务，可以使用

bash 复制代码

gradle :test

对于嵌套子项目，可以使用冒号指定完整路径

bash 复制代码

gradle :subproject:test

如果您运行一个不带任何冒号的任务，Gradle 会在当前目录的项目上下文中执行该任务

bash 复制代码

gradle test

咱们是一个 SpringBoot 单体项目，该怎么运行？

bash 复制代码

./gradlew bootRun

或者上面运行命令

bash 复制代码

gradle bootRun

设置文件基础

设置文件 (settings.gradle(.kts)) 是每个 Gradle 项目的入口点。

设置文件的主要目的是定义项目结构，通常是将子项目添加到构建中。因此，在

单项目构建中，设置文件是可选的。
多项目构建中，设置文件是强制性的，并声明所有子项目。

设置文件

设置文件是一个脚本，可以用 Groovy 写的 setting.gradle，也可以是 Kotlin 写的 settings.gradle.kts

设置文件通常位于项目的根目录中，因为它定义了构建的结构，例如包含哪些项目。如果没有设置文件，Gradle 默认会将构建视为单项目构建。

bash 复制代码

rootProject.name = 'root-project'   1

include('sub-project-a')            2
include('sub-project-b')
include('sub-project-c')

定义项目名称
添加子项目

设置脚本在任何构建脚本之前进行评估，使其成为启用或配置构建范围功能（如插件管理、包含的构建、版本目录等）的正确位置。

构建文件基础

通常，构建脚本 (build.gradle(.kts)) 详细说明了构建配置、任务和插件。

每个 Gradle 构建至少包含一个构建脚本。

构建脚本

在多项目构建中，每个子项目通常都有自己的构建文件，位于其根目录中。

单体项目

多项目，项目根目录下是没有的，只有每个子项目下有，其实不推荐项目根目录下放 build.gradle

构建脚本包含两种主要类型的依赖

Gradle 和构建脚本依赖：这包括 Gradle 本身或构建脚本逻辑所需的插件和库。
项目依赖：项目源代码正确编译和运行所需的库。

Groovy 复制代码

plugins {   1
    // Apply the application plugin to add support for building a CLI application in Java.
    id 'application'
}
dependencies {  2
    // Use JUnit Jupiter for testing.
    testImplementation libs.junit.jupiter

    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

    // This dependency is used by the application.
    implementation libs.guava
}
application {   3
    // Define the main class for the application.
    mainClass = 'org.example.App'
}

1. 添加插件

插件扩展了 Gradle 的功能，并可以为项目贡献任务。

groovy 复制代码

plugins {
	id 'java'
	id 'org.springframework.boot' version '4.0.5'
	id 'io.spring.dependency-management' version '1.1.7'
}

id 后面跟的就是插件名

java 插件为项目添加了 Java 编译以及测试和捆绑功能。

2. 添加依赖

groovy 复制代码

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter'
	compileOnly 'org.projectlombok:lombok'
	annotationProcessor 'org.projectlombok:lombok'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
	testCompileOnly 'org.projectlombok:lombok'
	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
	testAnnotationProcessor 'org.projectlombok:lombok'
}

项目需要外部库才能编译、运行和测试。这些是添加的依赖

比如 lombok 这里加了四种，compileOnly annotationProcessor testCompileOnly testAnnotationProcessor。没有 maven 简介，一个依赖就行

Gradle 需要每种情况都声明

3. 使用约定属性

插件为项目添加任务。它还为项目添加属性和方法。application 插件定义了打包和分发应用程序的任务，例如 run 任务。Application 插件提供了一种声明 Java 应用程序主类的方法，这是执行代码所必需的。

bash 复制代码

application {   
    // Define the main class for the application.
    mainClass = 'org.example.App'
}

在此示例中，主类（即程序执行开始的点）是 org.example.App。

构建脚本在构建的配置阶段进行评估，它们充当定义（子）项目构建逻辑的主要入口点。除了应用插件和设置约定属性外，构建脚本还可以

声明依赖
配置任务
引用共享设置（来自版本目录或约定插件）

依赖项基础

Gradle 内置支持依赖管理。

声明依赖

groovy 复制代码

plugins {
    id("java-library")  1
}

dependencies {
    implementation("com.google.guava:guava:32.1.2-jre") 2
    api("org.apache.juneau:juneau-marshall:8.2.0")      3
}

应用 Java Library 插件，它增加了构建 Java 库的支持。
添加对生产代码中使用的 Google Guava 库的依赖。
添加对库代码中使用的 Apache Juneau Marshall 库的依赖。

Gradle 中的依赖按配置分组，配置定义了何时以及如何使用依赖

implementation 用于编译和运行你的生产代码所需的依赖。
api 用于应暴露给库消费者的依赖。

还有别的 testImplementation、runtimeOnly、compileOnly 等

查看项目依赖

bash 复制代码

./gradlew :app:dependencies # :app 是项目名称

如果是单体项目，直接如下命令就可以

bash 复制代码

 ./gradlew dependencies

使用版本目录

版本目录提供了一种集中且一致的方式来管理整个构建中的依赖坐标和版本。无需在每个 build.gradle(.kts) 文件中直接声明版本，而是在 libs.versions.toml 文件中一次性定义它们。

版本目录通常包含四个部分

[versions] 用于声明插件和库将引用的版本号。
[libraries] 用于定义构建文件中使用的库。
[bundles] 用于定义一组依赖。
[plugins] 用于定义插件。

toml 复制代码

[versions]
guava = "32.1.2-jre"
juneau = "8.2.0"

[libraries]
guava = { group = "com.google.guava", name = "guava", version.ref = "guava" }
juneau-marshall = { group = "org.apache.juneau", name = "juneau-marshall", version.ref = "juneau" }

将此文件放在项目的 gradle/ 目录下，命名为 libs.versions.toml。Gradle 将自动识别它并通过构建脚本中的 libs 访问器暴露其内容。

定义后，可以直接在构建文件中引用这些别名

groovy 复制代码

dependencies {
    implementation(libs.guava)
    api(libs.juneau.marshall)
}

toml 文件里面出现的 xx-xx，在 build.gradle 里面直接写 xx.xx 就可以

任务基础

任务表示构建执行的某个独立工作单元，例如编译类、创建 JAR、生成 Javadoc 或将归档发布到仓库。

任务是每个 Gradle 构建的组成部分。

常见的任务类型包括：

编译源代码
运行测试
打包输出（例如，创建 JAR 或 APK）
生成文档（例如，Javadoc）
将构建产物发布到仓库

每个任务都是独立的，但可以依赖其他任务先运行。Gradle 利用此信息来找出执行任务的最有效顺序 --- 跳过任何已经是最新的内容。

运行任务

要运行任务，从项目根目录使用 Gradle Wrapper。例如，运行 build 任务：

bash 复制代码

$ ./gradlew build

这将运行 build 任务及其所有依赖项。

列出可用任务

Gradle 插件和您的构建脚本定义了项目中可用的任务。要查看它们：

bash 复制代码

$ ./gradlew tasks

这会显示一个分类的任务列表：

bash 复制代码

Application tasks
-----------------
run - Runs this project as a JVM application

Build tasks
-----------
assemble - Assembles the outputs of this project.
build - Assembles and tests this project.

...

Documentation tasks
-------------------
javadoc - Generates Javadoc API documentation for the main source code.

...

Other tasks
-----------
compileJava - Compiles main Java source.

...

您可以使用 ./gradlew 命令直接运行这些任务中的任何一个。

运行任务

如果您的构建文件中应用了 application 插件，则 run 任务应该可用。(插件也会提供可用任务)

bash 复制代码

$ ./gradlew run

输出示例：

bash 复制代码

> Task :app:compileJava
> Task :app:processResources NO-SOURCE
> Task :app:classes

> Task :app:run
Hello World!

BUILD SUCCESSFUL in 904ms
2 actionable tasks: 2 executed

Gradle 运行了执行应用程序所需的所有任务，包括先编译它。在此示例中，run 任务的输出是在控制台上打印的 Hello World 语句。

任务依赖

大多数任务不会独立运行。Gradle 知道哪些任务依赖于其他任务，并将自动以正确的顺序运行它们。

例如，当运行 ./gradlew build 时，Gradle 还会先运行 compileJava、test 和 jar 等任务 --- 因为 build 依赖于它们：

bash 复制代码

$ ./gradlew build

> Task :app:compileJava
> Task :app:processResources NO-SOURCE
> Task :app:classes
> Task :app:jar
> Task :app:startScripts
> Task :app:distTar
> Task :app:distZip
> Task :app:assemble
> Task :app:check
> Task :app:build

BUILD SUCCESSFUL in 764ms
7 actionable tasks: 7 executed

无需担心排序 --- Gradle 会自动处理。

插件基础

Gradle 构建于一个灵活的插件系统之上。

开箱即用，Gradle 提供核心基础架构，如依赖解析、任务编排和增量构建。大多数功能------如编译 Java、构建 Android 应用或发布构件------都来自插件。

插件是一个可重用的软件，它为 Gradle 构建系统提供了额外的功能。它可以

为你的构建添加新任务（如 compileJava 或 test）
添加新配置（如 implementation 或 runtimeOnly）
贡献 DSL 元素（如 application {} 或 publishing {}）

插件使用 plugins 块应用于构建脚本，它们带来了特定领域或工作流所需的所有逻辑。

常用插件

以下是一些流行的插件及其功能

Java 库插件（java-library）

编译 Java 源代码，生成 Javadoc，并将类打包成 JAR。添加了 compileJava、javadoc 和 jar 等任务。
Google 服务插件（com.google.gms.google-services）

在 Android 构建中配置 Firebase 和 Google API。添加了 googleServices {} 等 DSL 和 generateReleaseAssets 等任务。
Gradle Bintray 插件（com.jfrog.bintray）

使用 bintray {} 配置块将构件发布到 Bintray（或其他 Maven 风格的仓库）。

应用插件

构建脚本中使用插件 ID（一个全局唯一的标识符/名称）和版本来应用插件

text 复制代码

plugins {
    id("<<plugin id>>").version("<<plugin version>>")
}

kotlin 复制代码

plugins {
    id("java-library")
    id("com.diffplug.spotless").version("6.25.0")
}

应用内置的 java-library 插件，该插件添加了编译 Java、运行测试和打包库的任务。

应用社区维护的 spotless 插件（版本 6.25.0），该插件添加了代码格式化任务，并集成了 ktlint、prettier 和 google-java-format 等工具。

插件类型

Gradle 支持三种类型的插件

脚本插件 -- 可重用的 .gradle 或 .gradle.kts 文件，使用 apply from: 应用。
预编译插件 -- 打包的 Kotlin 或 Groovy 代码，使用 plugins {} 块应用。
二进制插件 -- 打包并发布的插件（通常来自插件门户或 Maven），使用 plugins {} 块应用。

大多数现代构建更喜欢二进制或预编译插件。

插件分发

Gradle 插件来自不同的来源，你可以根据你的用例选择正确的类型。

核心插件（内置于 Gradle）

Gradle 核心插件是 Gradle 分发包本身包含的一组插件。这些插件为构建和管理项目提供了基本功能。

核心插件的独特之处在于它们提供短名称，例如核心 JavaLibraryPlugin 的 java-library。你可以通过 ID 应用它们，无需额外设置

bash 复制代码

plugins {
    id("java-library")
}

这些插件由 Gradle 团队维护。

社区插件（来自插件门户）

社区插件是由 Gradle 社区开发而不是 Gradle 核心分发包的一部分的插件。这些插件提供了可能特定于某些用例或技术的额外功能。

Gradle 的插件生态系统包含数千个由社区共享的开源插件。这些插件发布到 Gradle 插件门户，可以通过 ID 和版本应用

bash 复制代码

plugins {
    id("org.springframework.boot").version("3.1.5")
}

当构建运行时，Gradle 将自动下载插件。

本地或自定义插件（在你的构建中定义）

你也可以编写自己的插件------无论是用于单个项目还是在同一构建中的多个项目之间共享。

最常见的自定义插件类型是约定插件，它存在于 buildSrc/ 目录或独立的 build-logic 模块中。这些插件用 Kotlin 或 Groovy 编写，并遵循与已发布插件相同的结构。

约定插件使用 plugins {} 块应用，就像外部插件一样

bash 复制代码

plugins {
    id("my.custom-conventions")
}