Gradle 使用详解

一. 前言

二. 下载与安装

2.1. 下载

2.2. 配置环境变量

2.3. 配置镜像

2.3.1. 全局设置

2.3.2. 项目级设置

三. Gradle 配置文件

3.1. build.gradle

3.2. settings.gradle

3.3. gradle.properties

3.4. init.d 目录

3.5. buildSrc 目录

四. Java Library 插件配置

五. 构建 SpringBoot 多模块项目

5.1. 项目结构

5.2. GradleMultiModule 模块

5.3. GradleParent 模块（公共）

5.4. GradleCommon 模块（公共）

5.5. GradleUtil 模块（公共）

5.6. GradleServer 模块（业务）

5.7. GradleOne 模块（业务）

5.8. GradleTwo 模块（业务）

5.9. GradleStart 启动模块（业务）

一. 前言

Gradle 是一个基于 Apache Ant 和 Apache Maven 概念的项目自动化构建开源工具。它使用一种基于 Groovy 的特定领域语言（DSL）来声明项目设置，也增加了基于 Kotlin 语言的 kotlin-based DSL，抛弃了基于 XML 的各种繁琐配置，面向 Java 应用为主。当前其支持的语言 C++、Java、Groovy、Kotlin、Scala 和 Swift，计划未来将支持更多的语言。

Gradle 是一个基于 JVM 的项目构建工具，是一款通用灵活的构建工具，支持 maven、Ivy…多种第三方仓库，支持传递性依赖管理，而不需要远程仓库或者是 pom.xml 和 ivy.xml 配置文件，使用基于 Groovy 编写的集简洁性和可支持语言多样性等特点的 build 脚本文件。

二. 下载与安装

2.1. 下载

安装前置要求：已存在 Java 环境。JDK 配置请参见《JDK 环境变量设置》。

下载官网：https://services.gradle.org/distributions/。

下载完成后解压：

2.2. 配置环境变量

在我们的系统环境变量中添加如下配置，步骤如下：

GRADLE_HOME：gradle 的目录；
GRADLE_USER_HOME：gradle 目录下的 repository 目录（解压后需新建）；
在系统的 Path 中配置 %GRADLE_HOME%\bin。

测试 Gradle 是否安装成功，保证必须配置完毕！

2.3. 配置镜像

2.3.1. 全局设置

在系统当前用户目录下新建一个 init.gradle 文件（也可以在 gradle 中的 init.d 文件夹中新建，在没有指定的情况下是读取当前用户目录下的配置）：

在 init.gradle 文件中添加如下配置：

allprojects {
  repositories {
    mavenLocal()
    maven {
      url 'https://maven.aliyun.com/repository/public/'
    }
    maven {
      url 'https://maven.aliyun.com/repository/central'
    }
    mavenCentral()
  }
}

2.3.2. 项目级设置

直接在创建的 Gradle 项目中的 build.gradle 文件中配置：

三. Gradle 配置文件

在 Gradle 中，可以有多个配置文件来定义构建过程和其他相关设置。其中，最主要的配置文件是 build.gradle，它通常位于项目的根目录下，用于定义项目的构建过程、依赖关系和其他构建相关的设置。

除此之外，还有其他的配置文件：

settings.gradle：用于配置 Gradle 的设置，例如定义项目的名称、子项目等信息。
gradle.properties：用于定义 Gradle 属性，例如设置构建缓存、定义构建版本等。
init.d 目录：用于在 Gradle 初始化时执行自定义的初始化脚本。
buildSrc 目录：用于存放与构建相关的代码，例如自定义任务、插件等。

这些配置文件在 Gradle 中扮演着不同的角色，用于定义构建过程、配置构建环境和执行构建任务等。

3.1. build.gradle

build.gradle 是 Gradle 构建工具的主要配置文件之一，用于定义项目的构建过程、依赖关系和其他构建相关的设置。在该文件中，您可以定义任务、插件、依赖项和其他构建相关设置。

build.gradle 分为项目级和模块级：

项目级：文件存在于根目录下，是整个项目的顶层 build.gradle。该 gradle 一般用来定义全局变量、依赖地址以及相关的清理操作。
模块级：存在于单个子模块下（即模块专属 gradle）。

以下是 build.gradle 文件中最常见的设置：

1. 定义项目名称和版本：

group 'com.example'
version '1.0.0'

2. 添加构建依赖项：

dependencies {
    implementation 'com.google.guava:guava:29.0-jre'
    testImplementation 'junit:junit:4.13.2'
}

3. 定义自定义任务：

task myTask {
    group("MyTask") // 设置分组
    doLast {
        println "This is my custom task."
    }
}

4. 应用插件：

plugins {
    id 'java'
}

5. 定义源代码目录：

sourceSets {
    main {
        java {
            srcDirs = ['src/main/java']
        }
    }
}

6. 配置编译选项：

compileJava {
    options.encoding = 'UTF-8'
}

3.2. settings.gradle

settings.gradle 是 Gradle 构建工具的配置文件之一，用于配置 Gradle 的全局设置以及多项目构建。在该文件中，您可以定义项目的名称、子项目、Gradle 插件、Gradle 版本等设置。

以下是 settings.gradle 文件中最常见的设置：

1. 定义项目名称：

rootProject.name = 'my-project'

2. 定义子项目：

include 'module1', 'module2'

3. 定义包含子项目的目录：

include 'module1:submodule1', 'module2:submodule2'

4. 排除子项目：

exclude 'module3'

5. 配置 Gradle 插件：

pluginManagement {
    repositories {
        gradlePluginPortal()
        maven {
            url 'https://plugins.gradle.org/m2/'
        }
    }
}

6. 配置 Gradle 版本：

gradle.version = '8.6'

注意：settings.gradle 文件只在多项目构建时才会使用。如果您只需要进行单项目构建，不需要使用 settings.gradle 文件。

3.3. gradle.properties

gradle.properties 是 Gradle 构建工具的配置文件之一，用于定义构建脚本中使用的变量和属性。该文件通常用于定义一些公共的属性或配置，这些配置可以在构建过程中重复使用，例如依赖版本号、构建工具的版本号等。

以下是 gradle.properties 文件中最常见的设置：

1. 定义依赖版本号：

springVersion=5.3.10

2. 定义构建工具版本号：

gradleVersion=8.6

3. 定义其他属性：

myProperty=value

这些属性可以在 build.gradle 文件中使用。

例如，以下代码演示了如何在 build.gradle 文件中使用 gradle.properties 文件中定义的属性：

dependencies {
    implementation "org.springframework:spring-core:${springVersion}"
}

此外，还可以在 gradle.properties 文件中定义 Gradle 构建工具的全局配置，例如代理设置、Gradle 守护进程设置等。

gradle.properties 文件是 Gradle 构建过程中非常重要的一部分，它可以使构建脚本更加模块化和可维护。

注意：如果在 gradle.properties 和 build.gradle 文件中同时定义了同名属性，build.gradle 文件中定义的属性会覆盖 gradle.properties 文件中定义的属性。

3.4. init.d 目录

init.d 目录是 Gradle 构建工具用于初始化构建的目录之一。在该目录下，您可以添加一些初始化脚本，这些脚本会在 Gradle 构建时被执行。

通常，init.d 目录下的脚本可以用于执行一些通用的初始化任务，例如设置环境变量、添加仓库、定义插件等。这些脚本可以在多个项目中共享，可以使您的构建脚本更加模块化和可维护。

默认情况下，Gradle 不会在 init.d 目录下查找任何脚本文件。如果您需要 Gradle 查找并执行 init.d 目录下的脚本，需要在 settings.gradle 文件中添加以下配置：

//启动初始化脚本
enableFeaturePreview('GRADLE_METADATA')
apply from: 'gradle/init.gradle'

上面的配置启用了 Gradle 的实验特性 GRADLE_METADATA，并在 gradle/init.gradle 脚本中定义了初始化脚本的查找路径。然后，您可以在 gradle/init.d 目录下添加一些脚本文件，这些脚本文件会在 Gradle 构建时被执行。

例如，以下是一个简单的 gradle/init.d 目录下的脚本文件，用于添加一个 Maven 仓库：

allprojects {
    repositories {
        maven {
            url "https://maven.example.com/"
        }
    }
}

注意：init.d 目录下的脚本文件执行的顺序是根据文件名的字母顺序来确定的。如果您需要控制脚本文件的执行顺序，可以在文件名中添加一些数字前缀。例如，01-init.gradle 文件会在 02-init.gradle 文件之前被执行。

3.5. buildSrc 目录

buildSrc 是 Gradle 构建工具的一个特殊目录，用于创建和管理构建脚本中的插件和依赖。

buildSrc 目录下的代码会在项目构建之前被编译和执行，并且可以被项目中的其他构建脚本所使用。这意味着您可以在 buildSrc 目录下编写自定义插件或添加依赖，然后在项目的其他构建脚本中使用它们，从而实现更加灵活和可重用的构建过程。

通常，buildSrc 目录下的代码使用 Gradle 的 Groovy 插件或 Kotlin 插件进行编写，这样可以让您使用相同的语言和 API 来编写项目中的构建脚本和 buildSrc 目录下的代码。

例如，以下是一个简单的 buildSrc 目录下的 Groovy 代码文件，用于定义一个自定义的任务：

// buildSrc/src/main/groovy/com/example/MyTask.groovy
package com.example
import org.gradle.api.DefaultTask
import org.gradle.api.tasks.TaskAction
class MyTask extends DefaultTask {
    @TaskAction
    void myTaskAction() {
        println "Hello from my task!"
    }
}

然后可以在项目的 build.gradle 文件中使用该自定义任务：

// build.gradle
task myTask(type: com.example.MyTask)

在这个例子中，buildSrc 目录下的代码定义了一个名为 MyTask 的自定义任务，然后在项目的 build.gradle 文件中使用该自定义任务来创建一个名为 myTask 的任务。

注意：buildSrc 目录下的代码是按照相同的构建流程进行编译和执行的，因此您可以在该目录下使用任何 Gradle API 和依赖。另外，buildSrc 目录会自动添加到构建脚本的 classpath 中，因此您可以在项目的其他构建脚本中直接使用 buildSrc 目录下的代码。

四. Java Library 插件配置

下面的图表描述了在使用 Java Library 插件时如何设置配置：

绿色配置是用户应该用于声明依赖关系的配置。
粉色配置是组件在编译或与库运行时使用的配置。
蓝色配置是组件内部使用的配置，仅供其自身使用。

下一个图表描述了测试配置的设置：

表1，Java Library 插件，用于声明依赖关系的配置：

配置名称	作用	可消耗性	可解析性	描述
api	声明API依赖关系	否	否	在这里声明传递导出到消费者的依赖关系，用于编译时和运行时。
implementation	声明实现依赖关系	否	否	在这里声明纯粹为内部使用而不打算向消费者公开的依赖关系（在运行时仍然对消费者公开）。
compileOnly	声明仅编译依赖关系	否	否	在这里声明在编译时需要但在运行时不需要的依赖关系。这通常包括在运行时找到时会被屏蔽的依赖关系。
compileOnlyApi	声明仅编译API依赖关系	否	否	在这里声明模块和消费者在编译时需要但在运行时不需要的依赖关系。这通常包括在运行时找到时会被屏蔽的依赖关系。
runtimeOnly	声明运行时依赖关系	否	否	在这里声明仅在运行时需要而不在编译时需要的依赖关系。
testImplementation	测试依赖关系	否	否	在这里声明用于编译测试的依赖关系。
testCompileOnly	声明仅测试编译依赖关系	否	否	在这里声明仅在测试编译时需要但不应泄露到运行时的依赖关系。这通常包括在运行时找到时会被屏蔽的依赖关系。
testRuntimeOnly	声明测试运行时依赖关系	否	否	在这里声明仅在测试运行时需要而不在测试编译时需要的依赖关系。

表2，Java Library插件，消费者使用的配置：

配置名称	作用	可消耗性	可解析性	描述
apiElements	用于编译此库	是	否	此配置用于供消费者检索编译此库所需的所有元素。
runtimeElements	用于执行此库	是	否	此配置用于供消费者检索运行此库所需的所有元素。

配置名称

作用

可消

耗性

可解

析性

描述

apiElements

用于编译此库

是

否

此配置用于供消费者检索编译此库所需的所有元素。

runtimeElements

用于执行此库

是

否

此配置用于供消费者检索运行此库所需的所有元素。

表3，Java Library插件，库本身使用的配置：

五. 构建 SpringBoot 多模块项目

5.1. 项目结构

-GradleMultiModule
  -GradleParent          包装common、util的父模块（实际中可以不要，这里演示导包、传递依赖等）
    -GradleCommon         公共模块，用于装entity或者mapper等
    -GradleUtil           工具类模块
  -GradleServer          业务模块的父模块，用于给子模块统一导入springboot的包
    -GradleOne            业务模块1 - 依赖GradleCommon、GradleUtil
    -GradleTwo            业务模块2 - 依赖
    -GradleStart          启动模块 - 导入GradleOne、GradleTwo依赖，启动项目

5.2. GradleMultiModule 模块

顶级父模块，统一配置 build.gradle（还可以配置gradle的版本），配置所有模块的关系。

build.gradle 配置：

//插件
plugins {
    id 'java'
    id 'idea'
    id 'java-library'
    id 'org.springframework.boot' version '2.7.15'
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
}
 
//allprojects：所有模块生效
allprojects {
    // 配置项目信息
    group = 'com.cc'
    version = '0.0.1-SNAPSHOT'
    // 配置字符编码
    tasks.withType(JavaCompile).configureEach {
        options.encoding = 'UTF-8'
    }
 
    java {
        sourceCompatibility = '8'
        targetCompatibility = '8'
    }
 
    //仓库配置
    repositories {
        //本地
        mavenLocal()
        //阿里仓库
        maven { url 'https://maven.aliyun.com/repository/public/' }
        //公司仓库。必须用：https。Gradle默认情况下不允许使用不安全的协议，以提高安全性。
        maven { url 'https://******:****/repository/maven-public/' }
        //中央仓库
        mavenCentral()
    }
 
}
 
//subprojects：所有子模块生效——springboot配置、导包版本管理、打包管理
subprojects {
    apply plugin: 'java'
    apply plugin: 'java-library'
    apply plugin: 'idea'
    //所有子模块都是springboot项目，如不是，不能打包。
    apply plugin: 'org.springframework.boot'
    apply plugin: 'io.spring.dependency-management'
 
    //所有子模块的-依赖版本管理
    dependencyManagement {
        dependencies {
            dependency 'cn.hutool:hutool-all:5.0.7'
            dependency "org.apache.commons:commons-lang3:3.5"
        }
    }
 
    //使用 gradle打包工具
    jar {
        manifest.attributes provider: 'gradle'
    }
 
    tasks.named('test') {
        useJUnitPlatform()
    }
 
}
 
// 配置gradle的版本
wrapper {
    //gradle的版本
    gradleVersion = '8.6'
    //版本类型：BIN、ALL（完全版，可以看gradle的代码）
    distributionType = 'ALL'
}

settings.gradle 配置：

rootProject.name = 'GradleMultiModule'
 
//公共模块总模块
include 'GradleParent'
include ':GradleParent:GradleCommon'
include ':GradleParent:GradleUtil'
project(':GradleParent:GradleCommon')?.name = 'GradleCommon'
project(':GradleParent:GradleUtil')?.name = 'GradleUtil'
 
//业务模块总模块
include 'GradleServer'
include ':GradleServer:GradleStart'
include ':GradleServer:GradleOne'
include ':GradleServer:GradleTwo'
project(':GradleServer:GradleStart')?.name = 'GradleStart'
project(':GradleServer:GradleOne')?.name = 'GradleOne'
project(':GradleServer:GradleTwo')?.name = 'GradleTwo'

5.3. GradleParent 模块（公共）

统一公共模块依赖。

build.gradle 配置：

// 配置所有子模块
subprojects {
    // 这里可以导入公共的依赖
    dependencies {
        // compileOnly：这样做可以确保Lombok在编译时可用，但不会包含在最终的构建产物中，从而减小构建产物的大小。
        // api：依赖可以传递给子模块
        // compileOnlyApi：仅编译时可用，不包含在构建产物中，并且可以传递给子模块
        compileOnlyApi 'org.projectlombok:lombok'
        // 表示将Lombok库作为注解处理器导入。
        annotationProcessor 'org.projectlombok:lombok'
    }
}

5.4. GradleCommon 模块（公共）

公共模块，存放Entity。

build.gradle 配置：

dependencies {
    // api可以传递依赖、implementation不能传递依赖
    // hutool工具类
    api 'cn.hutool:hutool-all'
}

5.5. GradleUtil 模块（公共）

存放所有工具类。

build.gradle 配置：

dependencies {
    // api可以传递依赖、implementation不能传递依赖
    api 'org.apache.commons:commons-lang3'
}

5.6. GradleServer 模块（业务）

业务模块的父模块，用于统一导入 SpringBoot 的包。

build.gradle 配置：

// 子模块生效
subprojects {
    // 配置子模块依赖
    dependencies {
        // 导入业务模块的公共包 - SpringBoot的包
        // 不用api，不用传递
        implementation 'org.springframework.boot:spring-boot-starter'
        implementation 'org.springframework.boot:spring-boot-starter-web'
        testImplementation 'org.springframework.boot:spring-boot-starter-test'
    }
}

5.7. GradleOne 模块（业务）

引入 GradleCommon、GradleUtil 模块，测试是否能使用引入模块的类、引入模块的依赖。

build.gradle 配置：

dependencies {
    // 依赖公共模块
    // api传递给子模块
    api project(":GradleParent:GradleCommon")
    api project(":GradleParent:GradleUtil")
}

5.8. GradleTwo 模块（业务）

引入 GradleCommon、GradleUtil 模块，测试是否能使用引入模块的类、引入模块的依赖。

build.gradle 配置：

dependencies {
    // 依赖公共模块：implementation不传递依赖；api传递依赖
    // 这里不传递依赖，因为会造成GradleStart有多个重复依赖
    implementation project(":GradleParent:GradleCommon")
    implementation project(":GradleParent:GradleUtil")
}

5.9. GradleStart 启动模块（业务）

引入所有业务模块，启动springboot项目。

build.gradle 配置：

dependencies {
    // 依赖GradleOne、GradleTwo，将该模块纳入启动中（加入springboot项目中）
    api project(':GradleServer:GradleOne')
    api project(':GradleServer:GradleTwo')
 
    // 其他依赖项...
}