构建工具Gradle入门实践

Gradle概述

Gradle是跟Apache Maven类似的项目构建工具，同时也用于管理项目依赖。

Gradle相比较Maven具备如下特性：

灵活性：Gradle的设计方式使其在最基本层面上可扩展，还可以用于使用C/C++的原生开发，并且可以扩展到涵盖任何生态系统
性能：对各种项目在常见场景中进行了性能测量，Gradle比Maven快100倍
依赖管理：Gradle允许自定义依赖项范围，这提供了更好的建模和更快的构建

Gradle核心概念

Gradle的核心概念：

项目

Gradle项目是一个可以构建的软件，例如应用程序或库
单项目构建包括一个称为根项目的单一项目
多项目构建包括一个根项目和任意数量的子项目

依赖项和依赖管理

依赖管理是一种自动化技术，用于声明和解析项目所需的外部资源
每个项目通常包含许多Gradle在构建期间解析的依赖项

构建脚本

构建脚本详细说明了Gradle构建项目所需的步骤
每个项目可以包含一个或多个构建脚本
Gradle脚本可以使用Groovy DSL或Kotlin DSL编写

任务

任务是工作的基本单位，例如编译代码或运行测试
每个项目包含一个或多个在构建脚本或插件中定义的任务

插件

插件用于扩展Gradle的功能
插件可选择性地为项目贡献任务

Gradle项目结构

使用Gradle作为构建工具的项目结构（以构建脚本使用Groovy DSL编写为例）如下：

Project
|--.gradle                         # Gradle生成的特定于项目的缓存目录
|  |--:
|--gradle                          # 包含Gradle Wrapper的JAR文件和配置
|  |--libs.versions.toml           # 版本目录，用于在中心位置定义一组依赖项的版本
|  |--wrapper
|     |--gradle-wrapper.jar
|     |--gradle-wrapper.properties
|--gradlew                         # 用于使用Gradle Wrapper执行构建的macOS和Linux脚本
|--gradlew.bat                     # 用于使用Gradle Wrapper执行构建的Windows脚本
|--settings.gradle                 # 项目的设置文件，其中定义了子项目列表
|--app                             # Java应用程序的源代码和构建配置目录
|  |--build                        # Java应用程序构建输出目录
|  |--src                          # Java应用程序源代码目录
|     |--main
|     |--test
|  |--build.gradle                 # Java应用程序的构建配置文件
|--:                               # 可能存在一些额外的Git文件，例如：.gitignore或.gitattributes

Gradle管理的目录

Gradle使用两个主要目录来执行和管理其工作：

Gradle用户主目录

Gradle用户主目录可以通过环境变量GRADLE_USER_HOME进行设置，可以类比为Maven的.m2目录。
Gradle用户主目录存储全局配置属性、初始化脚本、缓存和日志文件，默认情况下它的路径如下：

Mac或Linux系统下为：~/.gradle
Windows系统下为： C:\Users\<USERNAME>\.gradle

Gradle用户主目录内容随着版本的不同而有所差异，大致结构如下：

.gradle
|--caches                          # 全局缓存目录（用于非项目特定的所有内容）
|  |--8.5                          # 版本特定的缓存（例如，支持增量构建）
|  |--modules-2                    # 共享缓存（例如，用于依赖项的 artifact）
|--daemon                          # Gradle Daemon 的注册表和日志
|  |--8.5 
|--wrapper                         # Gradle Wrapper下载的发布版

项目根目录

使用Gradle作为构建工具的项目根目录包含项目的所有源文件，它还包含Gradle生成的文件和目录，例如：.gradle和build。
关于项目根目录的结构详见Gradle项目结构。

Gradle实践

安装Gradle

如下以在Windows系统中手动安装Gradle为例阐述。

由于不同的Gradle版本依赖的JDK版本所有不同，根据实际需要参考Gradle版本与JDK版本的对应关系从这里下载对应版本的Gradle安装包。

将Gradle安装包（例如只下载二进制文件：gradle-${VERSION}-bin.zip）解压到指定目录后设置环境变量：GRADLE_USER_HOME路径（如果不明确设置则默认路径为~/.gradle）。

初始化项目

如下以在Windows系统中初始化一个Java项目（项目名称为：test-gradle，安装的Gradle版本为gradle-8.5，Gradle脚本以Groovy DSL编写）为例进行说明。

# 创建目录
mkdir test-gradle
cd test-gradle

# 使用以下参数运行 gradle init 以生成 Java 应用程序
# 在执行这一步时会使用Gradle Wrapper初始化项目，如果在$GRADLE_USER_HOME/.gradle/wrapper/dists/gradle-8.5-bin/XXXXXXXXXXXXXXXXXXXXXXXXX/目录下不存在文件gradle-8.5-bin.zip，Gradle会尝试下载
# 但是由于防火墙的关系可能无法正常下载gradle-8.5-bin.zip，此时可以手动将gradle-8.5-bin.zip拷贝到该目录下后再次执行
gradle init --type java-application  --dsl groovy

特别说明：
在执行命令gradle init --type java-application --dsl groovy时，会使用Gradle Wrapper初始化项目，如果在$GRADLE_USER_HOME/.gradle/wrapper/dists/gradle-8.5-bin/XXXXXXXXXXXXXXXXXXXXXXXXX/目录下不存在文件gradle-8.5-bin.zip，Gradle会尝试下载。但是由于防火墙的关系可能无法正常下载gradle-8.5-bin.zip，此时可以手动将gradle-8.5-bin.zip下载并拷贝到该目录下后再次执行项目初始化命令。

接下来在命令行中根据提示步骤进行操作即可生成一个完整的Gradle项目结构：

Starting a Gradle Daemon (subsequent builds will be faster)

Select test framework:
  1: JUnit 4
  2: TestNG
  3: Spock
  4: JUnit Jupiter
Enter selection (default: JUnit Jupiter) [1..4] 1 # 这里选择1使用JUnit 4作为单元测试框架

Project name (default: test-gradle): # 这里直接回车适应默认项目名

Source package (default: test.gradle): # 这里直接回车使用默认包名

Enter target version of Java (min. 7) (default: 11): # 这里直接回车使用系统默认的JDK版本
Generate build using new APIs and behavior (some features may change in the next minor release)? (default: no) [yes, no] # 这里输入no


> Task :init
To learn more about Gradle by exploring our Samples at https://docs.gradle.org/8.5/samples/sample_building_java_applications.html

BUILD SUCCESSFUL in 31s
2 actionable tasks: 2 executed

生成的项目结构如下：

test-gradle
|--.gradle
|--app                        # Java应用程序模块目录
|  |--src                     # Java应用程序源代码目录
|  |  |--main
|  |  |--test
|  |--build.gradle            # Java应用程序的构建配置文件
|--gradle                     # 包含Gradle Wrapper的JAR文件和配置
|  |--libs.versions.toml      # 用于在中心位置定义一组依赖项的版本
|  |--wrapper                 # 
|--.gitattributes
|--.gitignore
|--gradlew                    # 用于使用Gradle Wrapper执行构建的macOS和Linux脚本
|--gradlew.bat                # 用于使用Gradle Wrapper执行构建的Windows脚本
|--settings.gradle            # 项目的设置文件，其中定义了子项目列表

在IDEA中打开项目，如下图：
在IDEA中打开Gradle项目

注意： 在IDEA中默认的Gradle用户主目录为C:\Users\<USERNAME>\.gradle，如下图：
IDEA中的Gradle默认用户主目录

需要将该参数设置为$GRADLE_USER_HOME环境变量指向的路径，如：E:\.gradle。

添加项目模块

使用gradle init命令初始化项目时默认生成了一个名为app的模块，如果需要添加新的模块，可以在IDEA中进行图形化操作。
在IDEA中添加Gradle模块1
在IDEA中添加Gradle模块2

执行上述操作后，将会在项目配置文件settings.gradle中添加一行新的配置：include 'client'，表示将新添加的目录（名称为client）作为一个Gradle模块添加到根项目中。

rootProject.name = 'test-gradle'
include('app')
include 'client'

添加依赖

项目中的依赖项在配置文件test-gradle/gradle/libs.versions.toml中进行统一管理，需要添加的依赖配置也在该文件中进行配置即可。

[versions]
guava = "32.1.2-jre"
junit = "4.13.2"
okhttp2 = "2.7.5" # 在这里指定依赖项版本

[libraries]
okhttp2 = {module = "com.squareup.okhttp:okhttp", version.ref = "okhttp2" } # 在这里配置具体的依赖项参数

然后在新添加的模块（名称为client）中引用依赖项（在配置文件test-gradle/client/build.gradle）：

dependencies {
    implementation libs.okhttp2
}

最后在client中引用依赖API，如下：

OkHttpClient mOkHttpClient = new OkHttpClient();
final Request request = new Request.Builder()
        .url("https://www.baidu.com")
        .build();
Response response = mOkHttpClient.newCall(request).execute();
if (response.isSuccessful()) {
    System.out.println(response.body().string());
}

应用插件

可以使用Gradle插件来完成相应任务，比如：将项目构建为可运行应用程序，代码风格检查等等。

Gradle插件按类型可以分为3类：

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

预编译插件和二进制插件更加常用。

更多Gradle插件信息详见：插件基础，Gradle 插件参考。

在Gradle插件中通常会定义许多任务，可以通过执行指定任务来完成特定工作。

执行Gradle任务有2种方式：

在命令行中执行，例如：在Windows系统中可以执行gradlew.bat :app:jar来实现对app模块打包
在IDEA集成开发环境中，在Gradle面板中双击执行Tasks节点下相应任务

使用java插件

如果希望将Gradle项目模块打包成可运行的jar包，可以使用java插件实现。

// test-gradle\app\build.gradle

plugins {
    id 'java'
}

// 配置jar任务
jar {
    // 1. 指定主类（替换为你的主类全限定名，如 com.example.Main）
    manifest {
        attributes 'Main-Class': 'test.gradle.App'
    }

    // 2. 打包所有运行时依赖到Jar中（避免运行时ClassNotFoundException）
    from {
        configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }
    }

    // 3. 解决META-INF文件重复冲突
    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
}

运行任务gradlew.bat :app:jar即可在test-gradle\app\build\libs路径下生成可执行文件：app.jar。

使用application插件

application插件使得在开发过程中在本地启动应用程序以及将应用程序打包为TAR或ZIP（包括特定于操作系统的启动脚本）变得容易，所以该插件几乎是每一个Gradle项目必备。

// test-gradle\app\build.gradle

plugins {
    id 'application'
}

application {
    // 指定应用程序的主类（即入口点）
    mainClass = 'test.gradle.App'
}

运行任务：gradlew.bat :app:distZip即可在test-gradle\app\build\distributions路径下生成可通过脚本启动应用的程序压缩包：app.zip。

其他事项

Gradle不同版本之间存在使用差异，因此一定要找到对应版本的文档进行查阅才是最准确的，参考：Gradle 8.5版本官方文档。
中文版文档未明确区分版本，所以在查阅时某些配置或命令的用法可能存在疑惑，以指定版本的文档为准，参考：Gradle 中文版文档（未区分Gradle版本）。

另外，不同的Gradle版本依赖的最低Java版本也不同，需要下载对应项目使用Java版本匹配的Gradle，否则使用过程中可能会出现报错，详见：Gradle版本与Java版本的对应关系

posted @ 2025-12-04 20:56 nuccch 阅读(0) 评论(0) 收藏举报

刷新页面返回顶部

编程随笔

感兴趣的技术：开发框架，中间件，分布式架构，DevOps

特别说明：本博客属于个人的开发随笔整理，其中的文字可能会随着理解的深入或者变化进行修改，有幸被转载时请标注原始链接^-^

构建工具Gradle入门实践

Gradle概述

Gradle核心概念

Gradle项目结构

Gradle管理的目录

Gradle用户主目录

项目根目录

Gradle实践

安装Gradle

初始化项目

添加项目模块

添加依赖

应用插件

使用java插件

使用application插件

其他事项

公告

编程随笔

感兴趣的技术：开发框架，中间件，分布式架构，DevOps 特别说明：本博客属于个人的开发随笔整理，其中的文字可能会随着理解的深入或者变化进行修改，有幸被转载时请标注原始链接^-^

构建工具Gradle入门实践

Gradle概述

Gradle核心概念

Gradle项目结构

Gradle管理的目录

Gradle用户主目录

项目根目录

Gradle实践

安装Gradle

初始化项目

添加项目模块

添加依赖

应用插件

使用java插件

使用application插件

其他事项

公告

感兴趣的技术：开发框架，中间件，分布式架构，DevOps

特别说明：本博客属于个人的开发随笔整理，其中的文字可能会随着理解的深入或者变化进行修改，有幸被转载时请标注原始链接^-^