在本教程中,您将通过从头开始创建、构建和探索一个简单的 Java 应用程序来学习 Gradle 的核心概念。您将对 Gradle 任务、插件和项目结构有实际的理解。

在本节中,你将

  • 初始化一个新的 Gradle 项目

  • 构建项目

  • 回顾 Gradle 的项目结构

  • 在 IntelliJ IDEA 中打开项目(可选)

  • 探索 Gradle 文件和构建脚本

  • 了解 Gradle wrapper

步骤 0. 开始之前

  1. 确保您已安装 Gradle

  2. (可选)安装 IntelliJ IDEA。社区版是免费的。

本教程主要使用 macOS 和命令行进行示例,但 Windows 和 Linux 上的步骤类似。虽然我们偶尔会使用 IntelliJ IDEA 来探索项目,但您可以使用任何您喜欢的 IDE。

步骤 1. 初始化项目

要测试 Gradle 安装,请从命令行运行 Gradle

$ gradle

Welcome to Gradle 8.13.

Directory '/' does not contain a Gradle build.

To create a new build in this directory, run gradle init

如果未安装 Gradle,请参阅安装部分

创建一个名为 tutorial 的新目录并 cd 进入该目录

$ mkdir tutorial
$ cd tutorial

使用以下参数运行 gradle init 以生成 Java 应用程序

$ gradle init --type java-application  --dsl kotlin

对任何其他提示选择默认值。

如果您想尝试,可以通过修改 init 参数(例如 --type kotlin-application)来选择不同的应用程序类型。

完成后,目录应如下所示

tutorial
├── .gradle                 (1)
│   └── ⋮
├── gradle                      (2)
│   ├── libs.versions.toml  (3)
│   └── wrapper
├── gradlew                     (4)
├── gradlew.bat             (5)
├── settings.gradle.kts         (6)
├── app                     (7)
│   ├── build.gradle.kts
│   └── src
└── ⋮                           (8)
1 Gradle 生成的特定于项目的缓存目录。
2 包含Gradle 包装器的 JAR 文件和配置。
3 版本目录,用于在中心位置定义一组依赖项的版本。
4 用于使用 Gradle Wrapper 执行构建的 macOS 和 Linux 脚本。
5 用于使用 Gradle Wrapper 执行构建的 Windows 脚本。
6 项目的设置文件,其中定义了子项目列表。
7 Java 应用程序的源代码和构建配置。
8 可能存在一些额外的 Git 文件,例如 .gitignoregradle.properties
tutorial
├── .gradle                 (1)
│   └── ⋮
├── gradle                      (2)
│   ├── libs.versions.toml  (3)
│   └── wrapper
├── gradlew                     (4)
├── gradlew.bat             (5)
├── settings.gradle             (6)
├── app                     (7)
│   ├── build.gradle
│   └── src
└── ⋮                           (8)
1 Gradle 生成的特定于项目的缓存目录。
2 包含Gradle 包装器的 JAR 文件和配置。
3 版本目录,用于在中心位置定义一组依赖项的版本。
4 用于使用 Gradle Wrapper 执行构建的 macOS 和 Linux 脚本。
5 用于使用 Gradle Wrapper 执行构建的 Windows 脚本。
6 项目的设置文件,其中定义了子项目列表。
7 Java 应用程序的源代码和构建配置。
8 可能存在一些额外的 Git 文件,例如 .gitignoregradle.properties

步骤 2. 了解 Wrapper

Gradle Wrapper 是启动 Gradle 构建的首选方式。Wrapper 会下载(如果需要)然后调用构建中声明的特定 Gradle 版本。

在新创建的项目中,首先查看 Gradle Wrapper 使用的文件。它由 macOS 和 Linux 的 shell 脚本 以及 Windows 的批处理脚本 组成。

这些脚本允许您运行 Gradle 构建,而无需在系统上安装 Gradle。它还有助于确保不同的开发人员以及本地和 CI 机器之间的构建使用相同版本的 Gradle。

从现在开始,您将永远不会直接调用 Gradle;相反,您将使用 Gradle wrapper

步骤 3. 调用 Wrapper

通过输入以下命令使用 wrapper

$ ./gradlew build

在 Windows 中,命令是

$ gradlew.bat build

第一次运行 wrapper 时,如果 Gradle 二进制文件尚未安装在您的机器上,它会下载并缓存它们。

Downloading https://services.gradle.org/distributions/gradle-8.13-bin.zip
...

Welcome to Gradle 8.13!
...

Calculating task graph as no cached configuration is available for tasks: build

BUILD SUCCESSFUL in 4s
7 actionable tasks: 7 executed
Configuration cache entry stored.

Gradle Wrapper 旨在提交到源代码管理,以便任何人都可以在不首先安装和配置特定版本的 Gradle 的情况下构建项目。

在这种情况下,我们通过 wrapper 调用 Gradle 来构建我们的项目,因此我们可以看到 app 目录现在包含一个新的 build 文件夹

$ cd app
$ ls -al
drwxr-xr-x  10 gradle-user  staff  320 May 24 18:07 build
-rw-r--r--   1 gradle-user  staff  862 May 24 17:45 build.gradle.kts
drwxr-xr-x   4 gradle-user  staff  128 May 24 17:45 src
drwxr-xr-x  10 gradle-user  staff  320 May 24 18:07 build
-rw-r--r--   1 gradle-user  staff  862 May 24 17:45 build.gradle
drwxr-xr-x   4 gradle-user  staff  128 May 24 17:45 src

除非另有指定,否则构建过程生成的所有文件都将放入 build 目录。

步骤 4. 了解项目结构

让我们来看看标准的 Gradle 项目结构,并将其与我们的教程项目进行比较

project structure

一个 构建 包含

  1. 一个顶层 settings.gradle(.kts) 文件。

  2. 一个 根项目

  3. 一个或多个 子项目,每个子项目都有自己的 build.gradle(.kts) 文件。

某些构建可能在根项目中包含 build.gradle(.kts) 文件,但这并 推荐。

libs.versions.toml 文件是一个版本目录,用于依赖管理,您将在本教程的后续部分中了解它。

在本教程中

  1. 根项目 称为 tutorial,并在 settings.gradle 文件中使用 rootProject.name = "tutorial" 定义。

  2. 子项目 称为 app,并在 settings.gradle 文件中使用 include("app") 定义。

根项目可以在顶层目录中,也可以有自己的目录。

一个构建

  • 代表一组可以一起构建、测试和/或发布的软件。

  • 可以选择包含其他构建(即其他软件,如库、插件、构建时工具等)。

一个项目

  • 代表您架构的一部分——一个库、一个应用程序、一个 Gradle 插件等。

  • 可以选择包含其他项目。

步骤 5. 在 IDE 中查看文件(可选)

通过双击 tutorial 目录中的 settings.gradle.kts 文件,在 IntelliJ IDEA 中打开项目。对于 Groovy DSL 用户,您可能需要在单击 settings.gradle 文件时选择 IntelliJ IDEA 应用程序

intellij idea ide

在 IDE 中打开 settings.gradle(.kts)build.gradle(.kts) 文件

intellij idea open

步骤 6. 了解设置文件

一个项目由一个或多个子项目(有时称为模块)组成。

Gradle 读取 settings.gradle(.kts) 文件以确定哪些子项目构成项目构建。

查看您项目中的文件

settings.gradle.kts
plugins {
    // Apply the foojay-resolver plugin to allow automatic download of JDKs
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}

rootProject.name = "tutorial"
include("app")
settings.gradle
plugins {
    // Apply the foojay-resolver plugin to allow automatic download of JDKs
    id 'org.gradle.toolchains.foojay-resolver-convention' version '1.0.0'
}

rootProject.name = 'tutorial'
include('app')

tutorial 根项目包含 app 子项目。include 调用的存在将 app 目录转换为子项目。

步骤 7. 了解构建脚本

每个子项目都包含自己的 build.gradle(.kts) 文件。

build.gradle(.kts) 文件是构建过程的核心组件,并定义了构建项目所需的任务。

build.gradle(.kts) 文件由 Gradle 读取和执行。

仔细查看 app 子项目(在 app 目录下)中的构建文件

app/build.gradle.kts
plugins {   (1)
    // Apply the application plugin to add support for building a CLI application in Java.
    application
}

repositories {
    // Use Maven Central for resolving dependencies.
    mavenCentral()
}

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)
}

// Apply a specific Java toolchain to ease working on different environments.
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

application {   (3)
    // Define the main class for the application.
    mainClass = "org.example.App"
}

tasks.named<Test>("test") {
    // Use JUnit Platform for unit tests.
    useJUnitPlatform()
}
app/build.gradle
plugins {   (1)
    // Apply the application plugin to add support for building a CLI application in Java.
    id 'application'
}

repositories {
    // Use Maven Central for resolving dependencies.
    mavenCentral()
}

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
}

// Apply a specific Java toolchain to ease working on different environments.
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

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

tasks.named('test') {
    // Use JUnit Platform for unit tests.
    useJUnitPlatform()
}

此构建脚本让 Gradle 知道 app 子项目正在使用哪些依赖项和插件以及在哪里找到它们。

我们将在以下部分中更详细地介绍这一点。

下一步: 运行任务 >>