使用 Gradle 构建 Java 应用

1. 概述

本文将手把手带你用 Gradle 构建一个 Java 项目，全程实战，不讲虚的。

我们会从零开始搭建项目结构，配置基础环境，引入 Java 插件和 JUnit 依赖，最后完成编译、测试和运行。
此外，还会介绍如何使用 Gradle 内置的 build-init 插件快速生成项目骨架——这在实际开发中能省不少事，避免重复踩坑。

对 Gradle 基础概念不熟悉的读者，可先参考文章 Gradle 入门介绍。

2. Java 项目结构

要使用 Gradle，首先得确保本地已安装 Gradle。安装方法参考官方文档：Gradle 安装指南。

接下来，我们创建项目目录。以 PowerShell 为例：

> mkdir gradle-employee-app

进入项目目录，创建标准的 Java 源码路径：

> mkdir src/main/java/employee

执行后目录结构如下：

Directory: D:\gradle-employee-app\src\main\java

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----        4/10/2020  12:14 PM                employee

在 employee 包下创建两个类：

✅ Employee 类：简单 POJO，包含姓名、邮箱和出生年份

public class Employee {
    String name;
    String emailAddress;
    int yearOfBirth;
}

✅ EmployeeApp 类：主程序入口，打印员工信息

public class EmployeeApp {

    public static void main(String[] args){
        Employee employee = new Employee();

        employee.name = "John";
        employee.emailAddress = "john.doe@company.com";
        employee.yearOfBirth = 1978;

        System.out.println("Name: " + employee.name);
        System.out.println("Email Address: " + employee.emailAddress);
        System.out.println("Year Of Birth:" + employee.yearOfBirth);
    }
}

⚠️ 注意：为便于演示，这里直接使用 public 字段。实际项目建议使用 private + getter/setter。

3. 构建 Java 项目

接下来，在项目根目录创建 build.gradle 文件：

Echo > build.gradle

跳过输入提示后，开始配置构建脚本。

3.1 配置 Application 插件

Gradle 通过插件扩展功能。我们要构建可执行的 Java 应用，需引入 Application Plugin：

apply plugin: 'application'
mainClassName = 'employee.EmployeeApp'

✅ 推荐写法（Gradle 4.10+）：

plugins {
    id 'application'
}
application {
    mainClass = 'employee.EmployeeApp'
}

3.2 添加自定义任务（可选）

Gradle 的构建过程由“任务（task）”组成。比如编译、测试、打包等都是任务。

你可以添加一个简单的任务用于调试配置阶段：

println 'This is executed during configuration phase'
task configured {
    println 'The project is configured'
}

3.3 执行构建

运行以下命令进行完整构建：

> gradle build

输出示例：

> Configure project :
This is executed during configuration phase
The project is configured
BUILD SUCCESSFUL in 1s
2 actionable tasks: 2 up-to-date

构建成功后，会生成 build 目录，结构如下：

├───build
│   ├───classes
│   │   └───java
│   │       ├───main
│   │       │   └───employee
│   │       │           Employee.class
│   │       │           EmployeeApp.class
│   │       └───test
│   ├───distributions
│   │       gradle-employee-app.tar
│   │       gradle-employee-app.zip
│   ├───libs
│   │       gradle-employee-app.jar
│   └───reports
│       └───tests
│           └───test
│               │   index.html

关键目录说明：

✅ classes/java/main：编译后的 .class 文件
✅ libs：生成的 JAR 包
✅ distributions：打包好的压缩包（含依赖和启动脚本）
✅ reports：测试报告（HTML 格式）

3.4 运行应用

使用 gradle run 直接运行主类：

> gradle run

输出结果：

> Task :run
Name: John
Email Address: john.doe@company.com
Year Of Birth:1978

BUILD SUCCESSFUL in 1s
2 actionable tasks: 1 executed, 1 up-to-date

3.5 使用 Gradle Wrapper

Wrapper 是项目级的 Gradle 执行器，保证团队成员使用统一版本，避免“在我机器上能跑”的尴尬。

在 build.gradle 中添加 wrapper 任务：

task wrapper(type: Wrapper){
    gradleVersion = '7.6'
}

✅ 建议使用较新稳定版，如 7.x 或 8.x

执行生成：

> gradle wrapper

生成文件包括：

│   gradlew
│   gradlew.bat
├───gradle
│   └───wrapper
│           gradle-wrapper.jar
│           gradle-wrapper.properties

✅ gradlew：Linux/Mac 启动脚本
✅ gradlew.bat：Windows 批处理
✅ gradle-wrapper.properties：指定 Gradle 版本

之后团队成员只需用 ./gradlew build 即可，无需手动安装 Gradle。

4. 添加依赖与单元测试

4.1 配置仓库和依赖

在 build.gradle 中添加仓库和依赖：

repositories {
    mavenCentral()  // 推荐使用 mavenCentral，jcenter 已归档
}

dependencies {
    implementation 'org.apache.commons:commons-lang3:3.12.0'
    testImplementation 'junit:junit:4.13.2'
}

⚠️ 注意：

jcenter() 已停止维护，建议改用 mavenCentral()

使用 implementation 替代旧的 compile

testImplementation 自动包含 testRuntime，无需重复声明

4.2 编写单元测试

创建测试目录：

mkdir src/test/java/employee

添加测试类：

import org.junit.Test;
import static org.junit.Assert.assertEquals;

public class EmployeeAppTest {

    @Test
    public void testData() {
        Employee testEmp = getEmployeeTest();
        assertEquals("John", testEmp.name);
        assertEquals("john.doe@company.com", testEmp.emailAddress);
        assertEquals(1978, testEmp.yearOfBirth);
    }

    private Employee getEmployeeTest() {
        Employee employee = new Employee();
        employee.name = "John";
        employee.emailAddress = "john.doe@company.com";
        employee.yearOfBirth = 1978;
        return employee;
    }
}

4.3 执行测试

清理并运行测试：

> gradle clean test

测试通过后，可在 build/reports/tests/test/index.html 查看详细报告。

5. 使用 Gradle Init 插件快速初始化

不想手动搭项目？Gradle 提供了 init 插件，一键生成项目骨架。

5.1 执行 init 命令

新建目录并执行：

> mkdir gradle-java-example
> cd gradle-java-example
> gradle init

按提示选择：

Select type of project to generate:
  1: basic
  ...
  6: java-application   ← 选这个
Select build script DSL:
  1: groovy             ← 选 Groovy（更常见）
  2: kotlin
Enter selection [1..10] 6

Select test framework:
  1: junit              ← 选 JUnit
Project name (default: gradle-java-example): 
Source package (default: gradle.java.example): employee

5.2 生成结果

目录结构自动生成：

├───src
│   ├───main
│   │   ├───java
│   │   │   └───employee
│   │   │           App.java
│   │   └───resources
│   └───test
│       ├───java
│       │   └───employee
│       │           AppTest.java
│       └───resources

主类内容为：

public class App {
    public String getGreeting() {
        return "Hello World!";
    }

    public static void main(String[] args) {
        System.out.println(new App().getGreeting());
    }
}

运行：

> gradle run

输出：

Hello world.

BUILD SUCCESSFUL in 1s
2 actionable tasks: 1 executed, 1 up-to-date

6. 总结

本文展示了两种构建 Java 项目的方式：

方式	优点	缺点
✅ 手动配置	灵活可控，适合学习原理	步骤繁琐，易出错
✅ `gradle init`	快速生成标准结构，减少样板代码	灵活性较低

建议：

学习阶段建议手动配置，理解 Gradle 构建流程
实际项目优先使用 gradle init 或 IDE 集成（如 IntelliJ 新建 Gradle 项目）

最终源码已上传至 GitHub：https://github.com/eugenp/tutorials/tree/master/gradle-modules/gradle/gradle-employee-app

Persistence

REST

Security