核心概念

理解 Gradle 的核心概念是掌握 Gradle 的关键。本章介绍 Gradle 中最重要的几个概念：Project（项目）、Task（任务）、Plugin（插件） 和 Lifecycle（生命周期）。

Project（项目）

每一个 Gradle 构建都由一个或多个 Project 组成。

单项目构建

my-app/
├── build.gradle.kts    ← 构建脚本，对应一个 Project
├── settings.gradle.kts ← 设置文件
└── src/
    └── main/java/...

多项目构建

my-company/
├── settings.gradle.kts       ← 声明所有子项目
├── build.gradle.kts          ← 根项目配置
├── core/
│   └── build.gradle.kts      ← core 子项目
├── web/
│   └── build.gradle.kts      ← web 子项目
└── api/
    └── build.gradle.kts      ← api 子项目

Project 的核心属性

属性	说明	示例
name	项目名称	"my-app"
group	项目组（对应 Maven groupId）	"com.example"
version	项目版本	"1.0.0"
projectDir	项目根目录	/home/user/my-app
buildDir	构建输出目录	/home/user/my-app/build

// build.gradle.kts
group = "com.example"
version = "1.0.0"
description = "My awesome application"

Task（任务）

Task 是 Gradle 构建的基本执行单元，代表一个具体的工作，例如编译代码、运行测试、生成文档。

任务的组成

tasks.register("greet") {
    group = "custom"              // 任务分组（便于查看）
    description = "打招呼任务"    // 任务描述
    
    doFirst {
        println("准备打招呼...")  // 任务开始前执行
    }
    
    doLast {
        println("Hello, Gradle!") // 任务主体
    }
}

常用内置任务

任务名	说明
build	完整构建（编译+测试+打包）
clean	清除 build 目录
test	运行所有测试
jar	打包为 JAR
compileJava	编译 Java 源码
dependencies	查看依赖树
tasks	列出所有可用任务

执行任务

# 执行单个任务
gradle build

# 执行多个任务
gradle clean build

# 跳过某个任务
gradle build -x test

# 查看所有任务
gradle tasks --all

Plugin（插件）

Plugin 通过向 Project 添加任务、配置、依赖项来扩展 Gradle 的功能。

插件类型

核心插件（Gradle 内置，直接使用 ID）：

plugins {
    java                   // Java 编译支持
    `java-library`         // Java 库，区分 api/implementation
    application            // 可执行应用程序
    `maven-publish`        // 发布到 Maven 仓库
}

社区插件（需要指定版本）：

plugins {
    id("org.springframework.boot") version "3.2.0"
    id("io.spring.dependency-management") version "1.1.4"
    kotlin("jvm") version "1.9.22"
}

插件做了什么？

以 java 插件为例，应用后自动获得：

• 任务：compileJava、test、jar、build、clean 等
• 源码集：src/main/java、src/test/java
• 依赖配置：implementation、testImplementation、runtimeOnly 等

Lifecycle（构建生命周期）

Gradle 的构建过程分为三个阶段：

初始化阶段 → 配置阶段 → 执行阶段
Initialization  Configuration  Execution

初始化阶段（Initialization）

• 读取 settings.gradle.kts
• 确定有哪些子项目参与本次构建
• 为每个项目创建 Project 对象

// settings.gradle.kts
rootProject.name = "my-company"
include("core", "web", "api")

配置阶段（Configuration）

• 执行所有 build.gradle.kts 中的配置代码
• 构建任务依赖图（DAG）
• 注意：配置阶段所有项目的构建脚本都会被执行，即使只运行一个任务

// 这段代码在配置阶段执行（不管运行哪个任务）
tasks.register("myTask") {
    println("配置阶段：注册任务")   // ← 配置阶段执行
    
    doLast {
        println("执行阶段：运行任务") // ← 执行阶段执行
    }
}

执行阶段（Execution）

• 按依赖顺序执行被选中的任务
• 跳过已缓存或未变更的任务（增量构建）

生命周期钩子

// 配置阶段完成后执行
gradle.projectsEvaluated {
    println("所有项目配置完成")
}

// 某个任务执行前
tasks.named("build") {
    doFirst { println("开始构建") }
}

构建文件概览

文件	作用	必须？
settings.gradle.kts	声明项目结构、子项目	是
build.gradle.kts	项目构建配置	是（根项目）
gradle.properties	键值对配置，可覆盖系统属性	否
gradlew / gradlew.bat	Gradle Wrapper 脚本	推荐
.gradle/	Gradle 缓存目录	自动生成
build/	构建输出目录	自动生成

术语速查

术语	解释
Build Script	构建脚本，即 build.gradle.kts
DSL	领域特定语言，Gradle 支持 Groovy DSL 和 Kotlin DSL
Configuration	依赖配置，如 implementation、testImplementation
Artifact	构建产物，如 JAR、WAR 文件
Repository	依赖仓库，如 Maven Central
Wrapper	Gradle 包装器，确保构建使用固定版本
DAG	有向无环图，描述任务间的依赖关系
Incremental Build	增量构建，跳过输入输出未变更的任务
Build Cache	构建缓存，跨机器复用构建结果

下一步

• 工作原理 - 深入了解 Gradle 内部机制
• 安装配置 - 开始动手实践
• Hello World - 第一个 Gradle 项目