在本教程中,你将从头开始创建一个简单的 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 Wrapper 的 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 Wrapper 的 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

一个构建 (build) 包含

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

  2. 一个根项目 (root project)

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

有些构建可能在根项目中包含 build.gradle(.kts) 文件,但不建议这样做。

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

在本教程中

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

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

根项目可以位于顶级目录或有自己的目录。

一个构建 (build)

  • 代表一组相关的软件,你可以一起构建、测试和/或发布它们。

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

一个项目 (project)

  • 代表你的架构中的一个独立部分——一个库、一个应用程序、一个 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 "0.9.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 '0.9.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 子项目正在使用哪些依赖项和插件以及在哪里找到它们。

我们将在接下来的章节中更详细地探讨这一点。

下一步: 运行任务 >>