使用 Gradle 构建 Java 项目

本指南将指导你使用 Gradle 构建一个简单的 Java 项目。

你将构建的内容

你将创建一个简单的应用程序，然后使用 Gradle 构建它。

你需要的内容

大约 15 分钟
一个喜爱的文本编辑器或 IDE
JDK 6 或更高版本

如何完成本指南

与大多数 Spring 入门指南一样，你可以从头开始完成每一步，也可以跳过你已经熟悉的设置步骤。无论哪种方式，你最终都会获得可用的代码。

要从头开始，请转到设置项目。

要跳过基础知识，请执行以下操作

下载并解压本指南的源代码存储库，或使用 Git 克隆它：git clone https://github.com/spring-guides/gs-gradle.git
cd 到 gs-gradle/initial
跳转到安装 Gradle。

完成之后，您可以根据 gs-gradle/complete 中的代码检查您的结果。

设置项目

首先，您设置一个 Java 项目，供 Gradle 构建。为了专注于 Gradle，现在尽可能让项目简单。

创建目录结构

在您选择的项目目录中，创建以下子目录结构；例如，在 *nix 系统上使用 mkdir -p src/main/java/hello

└── src
    └── main
        └── java
            └── hello

在 src/main/java/hello 目录中，您可以创建您想要的任何 Java 类。为了简单起见，并且为了与本指南的其余部分保持一致，Spring 建议您创建两个类：HelloWorld.java 和 Greeter.java。

src/main/java/hello/HelloWorld.java

package hello;

public class HelloWorld {
  public static void main(String[] args) {
  Greeter greeter = new Greeter();
  System.out.println(greeter.sayHello());
  }
}

src/main/java/hello/Greeter.java

package hello;

public class Greeter {
  public String sayHello() {
  return "Hello world!";
  }
}

安装 Gradle

现在您有一个可以使用 Gradle 构建的项目，您可以安装 Gradle。

强烈建议使用安装程序

SDKMAN
Homebrew (brew install gradle)

作为最后的手段，如果上述工具都不适合您的需求，您可以从 https://www.gradle.org/downloads 下载二进制文件。只需要二进制文件，因此查找指向 gradle-version-bin.zip 的链接。（您还可以选择 gradle-version-all.zip，以获取源代码和文档以及二进制文件。）

将文件解压缩到您的计算机，并将 bin 文件夹添加到您的路径中。

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

gradle

如果一切顺利，您会看到一条欢迎消息

:help

Welcome to Gradle 6.0.1.

To run a build, run gradle <task> ...

To see a list of available tasks, run gradle tasks

To see a list of command-line options, run gradle --help

To see more detail about a task, run gradle help --task <task>

For troubleshooting, visit https://help.gradle.org

Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
Use '--warning-mode all' to show the individual deprecation warnings.
See https://docs.gradle.org.cn/6.0.1/userguide/command_line_interface.html#sec:command_line_warnings

BUILD SUCCESSFUL in 455ms
1 actionable task: 1 executed

您现在已经安装了 Gradle。

了解 Gradle 的功能

现在已经安装了 Gradle，看看它能做什么。甚至在您为项目创建 build.gradle 文件之前，您可以询问它有哪些可用的任务

gradle tasks

您应该看到一个可用任务列表。假设您在尚未有 build.gradle 文件的文件夹中运行 Gradle，您会看到一些非常基本的任务，例如

:tasks

------------------------------------------------------------
Tasks runnable from root project
------------------------------------------------------------

Build Setup tasks
-----------------
init - Initializes a new Gradle build.
wrapper - Generates Gradle wrapper files.

Help tasks
----------
buildEnvironment - Displays all buildscript dependencies declared in root project 'gs-gradle'.
components - Displays the components produced by root project 'gs-gradle'. [incubating]
dependencies - Displays all dependencies declared in root project 'gs-gradle'.
dependencyInsight - Displays the insight into a specific dependency in root project 'gs-gradle'.
dependentComponents - Displays the dependent components of components in root project 'gs-gradle'. [incubating]
help - Displays a help message.
model - Displays the configuration model of root project 'gs-gradle'. [incubating]
outgoingVariants - Displays the outgoing variants of root project 'gs-gradle'.
projects - Displays the sub-projects of root project 'gs-gradle'.
properties - Displays the properties of root project 'gs-gradle'.
tasks - Displays the tasks runnable from root project 'gs-gradle'.

To see all tasks and more detail, run gradle tasks --all

To see more detail about a task, run gradle help --task <task>

Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
Use '--warning-mode all' to show the individual deprecation warnings.
See https://docs.gradle.org.cn/6.0.1/userguide/command_line_interface.html#sec:command_line_warnings

BUILD SUCCESSFUL in 477ms
1 actionable task: 1 executed

尽管这些任务可用，但如果没有项目构建配置，它们不会提供太多价值。当您完善 build.gradle 文件时，一些任务将变得更有用。随着您向 build.gradle 添加插件，任务列表将增长，因此您偶尔会想要再次运行 tasks 以查看有哪些任务可用。

说到添加插件，接下来您将添加一个启用基本 Java 构建功能的插件。

构建 Java 代码

从简单开始，在您在本指南开头创建的 <project folder> 中创建一个非常基本的 build.gradle 文件。只给它一行

apply plugin: 'java'

构建配置中的这一行带来了强大的功能。再次运行 gradle tasks，您会看到列表中添加了新任务，包括用于构建项目、创建 JavaDoc 和运行测试的任务。

您将经常使用 gradle build 任务。此任务编译、测试并将代码组装到 JAR 文件中。您可以像这样运行它

gradle build

几秒钟后，“BUILD SUCCESSFUL”表示构建已完成。

要查看构建工作的成果，请查看 build 文件夹。在其中，您会发现几个目录，包括以下三个值得注意的文件夹

classes。项目的已编译 .class 文件。
reports。构建生成的报告（例如测试报告）。
libs。已组装的项目库（通常是 JAR 和/或 WAR 文件）。

classes 文件夹有从编译 Java 代码生成的 .class 文件。具体来说，您应该找到 HelloWorld.class 和 Greeter.class。

此时，该项目没有任何库依赖项，因此 dependency_cache 文件夹中没有任何内容。

reports 文件夹应包含对项目运行单元测试的报告。由于该项目还没有任何单元测试，因此该报告将毫无趣味。

libs 文件夹应包含一个以项目文件夹命名的 JAR 文件。在下面，您将看到如何指定 JAR 的名称及其版本。

声明依赖项

简单的 Hello World 示例是完全独立的，并且不依赖于任何其他库。但是，大多数应用程序依赖于外部库来处理常见和/或复杂的功能。

例如，假设除了说“Hello World！”之外，您还希望应用程序打印当前日期和时间。您可以使用本机 Java 库中的日期和时间工具，但您可以通过使用 Joda Time 库使事情变得更有趣。

首先，将 HelloWorld.java 更改为如下所示

package hello;

import org.joda.time.LocalTime;

public class HelloWorld {
  public static void main(String[] args) {
    LocalTime currentTime = new LocalTime();
    System.out.println("The current local time is: " + currentTime);

    Greeter greeter = new Greeter();
    System.out.println(greeter.sayHello());
  }
}

此处 HelloWorld 使用 Joda Time 的 LocalTime 类来获取和打印当前时间。

如果您现在运行 gradle build 来构建项目，则构建将失败，因为您尚未在构建中将 Joda Time 声明为编译依赖项。

首先，您需要为第三方库添加一个源。

repositories { 
    mavenCentral() 
}

repositories 块指示构建应从 Maven Central 存储库解析其依赖项。Gradle 严重依赖 Maven 构建工具建立的许多约定和设施，包括使用 Maven Central 作为库依赖项源的选项。

现在我们已准备好使用第三方库，让我们声明一些库。

sourceCompatibility = 1.8
targetCompatibility = 1.8

dependencies {
    implementation "joda-time:joda-time:2.2"
    testImplementation "junit:junit:4.12"
}

使用 dependencies 块，您可以声明一个 Joda Time 依赖项。具体来说，您正在请求（从右向左读取）joda-time 组中 joda-time 库的 2.2 版本。

关于此依赖项的另一件需要注意的事情是，它是一个 compile 依赖项，表示它应该在编译时可用（如果您正在构建 WAR 文件，则包含在 WAR 的 /WEB-INF/libs 文件夹中）。其他值得注意的依赖项类型包括

implementation。编译项目代码所需的依赖项，但将在运行时由运行代码的容器提供（例如，Java Servlet API）。
testImplementation。用于编译和运行测试的依赖项，但不需要用于构建或运行项目的运行时代码。

最后，让我们为 JAR 工件指定名称。

jar {
    archiveBaseName = 'gs-gradle'
    archiveVersion =  '0.1.0'
}

jar 块指定 JAR 文件的命名方式。在这种情况下，它将呈现 gs-gradle-0.1.0.jar。

现在，如果您运行 gradle build，Gradle 应从 Maven Central 存储库解析 Joda Time 依赖项，并且构建将成功。

使用 Gradle Wrapper 构建您的项目

Gradle Wrapper 是启动 Gradle 构建的首选方式。它包含一个适用于 Windows 的批处理脚本和一个适用于 OS X 和 Linux 的 shell 脚本。这些脚本允许您运行 Gradle 构建，而无需在您的系统上安装 Gradle。这曾经是添加到构建文件中的内容，但它已被折叠到 Gradle 中，因此不再需要。相反，您只需使用以下命令。

$ gradle wrapper --gradle-version 6.0.1

此任务完成后，您将看到一些新文件。这两个脚本位于文件夹的根目录中，而 wrapper jar 和属性文件已添加到新的 gradle/wrapper 文件夹中。

└── <project folder>
    └── gradlew
    └── gradlew.bat
    └── gradle
        └── wrapper
            └── gradle-wrapper.jar
            └── gradle-wrapper.properties

Gradle Wrapper 现可用于构建您的项目。将其添加到您的版本控制系统中，克隆您项目的每个人都可以同样构建它。它可以与 Gradle 的已安装版本完全相同的方式使用。运行包装器脚本来执行构建任务，就像您之前所做的那样

./gradlew build

您第一次为特定版本的 Gradle 运行包装器时，它会下载并缓存该版本的 Gradle 二进制文件。Gradle Wrapper 文件旨在提交到源代码管理中，以便任何人都可以在无需首先安装和配置特定版本的 Gradle 的情况下构建项目。

在此阶段，您将构建您的代码。您可以在此处查看结果

build
├── classes
│   └── main
│       └── hello
│           ├── Greeter.class
│           └── HelloWorld.class
├── dependency-cache
├── libs
│   └── gs-gradle-0.1.0.jar
└── tmp
    └── jar
        └── MANIFEST.MF

包括 Greeter 和 HelloWorld 的两个预期类文件，以及一个 JAR 文件。快速浏览一下

$ jar tvf build/libs/gs-gradle-0.1.0.jar
  0 Fri May 30 16:02:32 CDT 2014 META-INF/
 25 Fri May 30 16:02:32 CDT 2014 META-INF/MANIFEST.MF
  0 Fri May 30 16:02:32 CDT 2014 hello/
369 Fri May 30 16:02:32 CDT 2014 hello/Greeter.class
988 Fri May 30 16:02:32 CDT 2014 hello/HelloWorld.class

类文件被捆绑在一起。需要注意的是，即使您将 joda-time 声明为依赖项，该库也不会包含在此处。并且 JAR 文件也无法运行。

为了使此代码可运行，我们可以使用 gradle 的 application 插件。将其添加到您的 build.gradle 文件中。

apply plugin: 'application'

mainClassName = 'hello.HelloWorld'

然后，您可以运行该应用程序！

$ ./gradlew run
:compileJava UP-TO-DATE
:processResources UP-TO-DATE
:classes UP-TO-DATE
:run
The current local time is: 16:16:20.544
Hello world!

BUILD SUCCESSFUL

Total time: 3.798 secs

捆绑依赖项需要更多思考。例如，如果我们正在构建 WAR 文件（一种通常与打包第三方依赖项关联的格式），我们可以使用 gradle 的 WAR 插件。如果您正在使用 Spring Boot 并且想要一个可运行的 JAR 文件，则 spring-boot-gradle-plugin 非常方便。在此阶段，gradle 对您的系统了解得不够，无法做出选择。但就目前而言，这应该足以开始使用 gradle。

为了总结本指南，以下是已完成的 build.gradle 文件

build.gradle

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'application'

mainClassName = 'hello.HelloWorld'

// tag::repositories[]
repositories { 
    mavenCentral() 
}
// end::repositories[]

// tag::jar[]
jar {
    archiveBaseName = 'gs-gradle'
    archiveVersion =  '0.1.0'
}
// end::jar[]

// tag::dependencies[]
sourceCompatibility = 1.8
targetCompatibility = 1.8

dependencies {
    implementation "joda-time:joda-time:2.2"
    testImplementation "junit:junit:4.12"
}
// end::dependencies[]

// tag::wrapper[]
// end::wrapper[]

此处嵌入了许多开始/结束注释。这使得可以将构建文件的部分内容提取到本指南中以进行上述详细说明。您无需在生产构建文件中使用它们。

摘要

恭喜！您现在已经为构建 Java 项目创建了一个简单但有效的 Gradle 构建文件。

另请参阅

以下指南可能也有帮助

使用 Maven 构建 Java 项目

想要编写新指南或为现有指南做出贡献？请查看我们的贡献指南。

所有指南均以 ASLv2 许可证发布代码，并以署名、禁止演绎创意共享许可证发布撰写内容。

获取代码

转到存储库