[!info] related notes

• 所属 MOC：工具链 · 学习路线
• 前置概念：Maven 基础 · 安装 JDK
• 后续概念：项目结构 · 测试
• 容易混淆：Groovy DSL vs Kotlin DSL

Gradle 基础

这个概念为什么出现

Gradle 在 Android 与许多服务端仓库流行：灵活的任务图、增量构建与多语言 DSL。理解其任务与依赖配置后，才能读懂现代 Java 仓库。

[!abstract] 一句话理解 Gradle 以任务图执行构建；Java 插件提供编译/测试/打包约定；依赖配置（implementation/api/testImplementation）控制编译类路径与暴露面。

最小可运行示例

场景：应用 Java 插件的最小构建

下面以 Gradle 8.14.3、已安装的 JDK 21 验证。保存为 build.gradle.kts；源码/测试目录分别为 src/main/java、src/test/java。toolchain 声明不保证自动下载 JDK，缺少本地 JDK 时需另配下载仓库。

// build.gradle.kts
plugins {
    java
}
repositories {
    mavenCentral()
}
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(21))
    }
}
dependencies {
    testImplementation(platform("org.junit:junit-bom:5.10.2"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}
tasks.test {
    useJUnitPlatform()
}

已有 wrapper 时运行以下命令；新目录需先用可信的 Gradle 安装执行 gradle wrapper --gradle-version 8.14.3，再把 wrapper 脚本、JAR 与配置纳入版本管理。示例版本用于复现，并非最新版本声明。

./gradlew test
./gradlew build
./gradlew dependencies

结合场景再看三个关注点

1. **Wrapper（gradlew）**固定 Gradle 发行版，但不单独锁定依赖、JDK 或外部输入。
2. implementation vs api 影响消费者编译。
3. 增量与缓存是性能关键，但正确性仍靠任务输入输出声明。

核心概念与准确模型

1. 项目与任务

• 任务有依赖
• build 聚合多种检查

2. 依赖配置

implementation 用于主代码编译与运行；runtimeOnly 仅运行时；testImplementation 用于测试。api 由 java-library 插件提供，不能在仅应用 java 的上述示例中直接使用。库的 api 依赖进入消费者编译类路径，implementation 依赖通常只进入消费者运行类路径。

3. 与 Maven 坐标

仍使用 Maven 中央等仓库坐标解析。

边界情况与反直觉行为

1. 配置阶段 vs 执行阶段副作用。
2. Version catalog 集中声明依赖/插件版本，不等于 dependency locking；动态版本与传递依赖仍可能变化。
3. 自定义任务忘记声明输入输出导致增量错误。

常见误区

[!warning] 常见误区：在构建脚本写重业务逻辑 构建脚本保持薄，复杂生成器用独立代码。

工程实践

1. 强制 wrapper。
2. 依赖目录化（catalog）。
3. CI 使用 ./gradlew --no-daemon 视环境权衡。
4. 与 Maven 仓库共存发布。

本节总结

• 任务图 + Java 插件
• 配置控制类路径暴露
• wrapper 固定构建工具版本，可复现还依赖依赖解析、JDK 与任务输入

自测题

1. 为什么推荐 gradlew 而不是全局 gradle？
2. api 与 implementation 对库作者意味着什么？

参考答案

1. 锁定版本，避免“我机器可以”。
2. api 依赖暴露给消费者编译；implementation 更好封装。

延伸阅读与资料来源

资料	类型	支撑内容
Gradle User Manual	官方	核心模型
Building Java Projects	官方	Java 插件