从 Gradle 到 Transform：Android 编译开发 Part 1 - Gradle 构建初探

Gradle 作为现代化构建工具的代表，凭借其灵活性和高效性，已成为 Java、Android 等开发领域的行业标准。本次分享《Gradle 构建初探》将系统性地讲解 Gradle 的核心概念与实践应用，帮助开发者构建高效、可维护的项目。通过本次分享您可以收获到：

Gradle 基础知识：定义、设计理念、发展历程、项目结构、生命周期等

Gradle 的使用：Gradle Task、Version Catalog 以及 Gradle Plugin

1. Gradle 概述

1.1 定义与定位

Gradle 是一个基于 JVM 的开源构建自动化工具 ，它结合了** Apache Ant 的灵活性和 Apache Maven 的依赖管理能力**，同时引入了基于 Groovy 或 Kotlin 的领域特定语言(DSL)，使得项目配置更加简洁高效，例如 android 项目中的 build.gradle(Groovy)以及 build.gradle.kts（Kotlin）。Gradle 被设计为通用的构建工具，可以构建几乎任何类型的软件，包括** Java 应用、Android 应用、C++项目**等。

Gradle 的核心定位是：

自动化构建：处理项目的编译、测试、打包和部署等过程

依赖管理：自动解析和下载项目所需的库文件

多项目支持：高效管理由多个子项目组成的复杂工程

跨平台构建：基于 JVM 实现，可在不同操作系统上运行

1.2 核心设计理念

Gradle 的设计起源于对更高效、灵活构建工具的需求，其核心设计理念包括：

对 Ant 和 Maven 的继承与发展

继承了 Maven 的依赖管理和项目结构约定

吸收了 Ant 的任务执行灵活性

摒弃了 XML 配置，采用更简洁的 DSL

性能优化

增量构建机制：仅重新构建发生变化的部分

构建缓存：重用之前构建的输出

守护进程：避免重复初始化开销

可扩展性

丰富的插件机制：例如 Android Gradle Plugin

支持自定义任务和构建逻辑

适应各种复杂项目需求

多语言支持

不仅支持 Java，还支持 Groovy、Kotlin、Scala 等 JVM 语言

计划支持更多语言

1.3 发展历程

1.3.1 构建工具的史前时代：Ant 与 Maven 的局限性

Gradle 的诞生并非偶然，而是对早期构建工具缺陷的回应。在 2000 年，Apache Ant 作为首个 Java 构建工具出现，其基于 XML 的配置方式虽然灵活，但缺乏标准化依赖管理 ，导致项目维护成本高昂。2004 年，Maven 通过引入中央仓库 和生命周期管理解决了依赖问题，但** XML 的冗长语法**（如一个简单的依赖声明需要 10 行以上代码）和僵化的约定配置，难以适应多语言、模块化项目的需求。

技术痛点 ： Maven 的 POM 文件在管理多模块项目时，常出现<dependencyManagement>嵌套过深的问题，而 Ant 的build.xml需要手动编写编译、打包的每个步骤。

1.3.2 Gradle 的诞生（2008--2012）：革命性设计理念

2012 年，由** Hans Dockter 团队发布的 Gradle，首次将编程式构建**引入主流。其核心创新包括：

Groovy DSL：用动态语言替代 XML，使构建脚本长度减少 70%以上（对比 Maven 的 POM 文件）。例如：

groovy 复制代码

// Gradle依赖声明 
dependencies {
    implementation 'org.springframework:spring-core:5.3.0'  // 1行
}

xml 复制代码

<!--Maven的XML-->
<project xmlns="http://maven.apache.org/POM/4.0.0" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>my-project</artifactId>
    <version>1.0</version>

    <dependencies>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-core</artifactId>
            <version>5.3.0</version>
        </dependency>
    </dependencies>
</project>

增量构建 ：通过任务输入/输出快照检查，跳过未变更的编译任务，显著提升性能。
多项目支持 ：通过settings.gradle定义模块化工程结构，解决 Maven 中需要拆分 POM 的痛点。

1.3.3 关键版本演进与技术突破

1.3.3.1 Gradle 早期版本奠定基础（2.x 时代）

Gradle 的 2.x 系列版本（2013-2016 年）为工具的核心能力奠定了基础，主要聚焦于构建模型确立和基础功能完善。

依赖管理突破：Gradle 2.0 首次引入了基于 Apache Ivy 改进的依赖管理系统，支持从 Maven 仓库获取依赖，解决了 Ant 时代依赖管理的痛点。其依赖解析算法能够处理复杂的传递依赖关系，相比 Ant 是一大飞跃

多项目构建支持 ：Gradle 2.1 引入了settings.gradle和多项目构建模型，允许通过include语句定义项目结构，支持项目间依赖共享。这为大型项目拆分模块提供了标准方式

Android 生态适配 ：Gradle 2.2 版本开始为 Android 开发提供专门支持，包括对 Android N(API 24)和 Java 8 语言特性的兼容，使 Gradle 逐渐成为 Android 官方构建工具

性能优化初探 ：Gradle 2.3 开始引入增量编译概念，通过记录任务的输入输出，在后续构建中跳过未变化的代码，显著提升构建速度。这一机制成为后来 Gradle 性能优势的核心基础

版本	发布时间	核心创新
2.0	2013 年	引入改进的依赖管理系统
2.1	2014 年	支持多项目构建模型
2.2	2015 年	增加 Android 构建支持
2.3	2016 年	引入增量编译概念

1.3.3.2 Gradle 成熟期技术飞跃（3.x-5.x 时代）

2016-2019 年的 3.x 到 5.x 版本是 Gradle 技术架构趋于成熟的阶段，在性能、语言支持和工具链整合等方面实现重大突破。

构建性能革命性提升

依赖管理增强 ：Gradle 3.0 引入了implementation和api配置替代传统的compile，更精确地控制依赖传递，避免泄漏不必要的依赖到消费方。这一改进显著减少了因依赖冲突导致的构建问题。

构建缓存技术 ：Gradle 3.5 引入了构建缓存 机制，允许跨项目甚至跨机器复用任务输出，结合--build-cache参数可显著减少 CI 环境构建时间。测试表明，全量构建时间可缩短 40%以上。

并行执行优化 ：从 Gradle 4.0 开始，任务并行执行 成为默认行为，Gradle 会自动分析任务依赖图，并行执行独立任务，充分利用多核 CPU 性能。配合--parallel参数可自定义并行度。

语言与平台支持扩展

Kotlin DSL 支持：Gradle 4.0 首次支持 Kotlin 作为 DSL 语言（除 Groovy 外），为 Kotlin 开发者提供类型安全、IDE 支持更好的构建脚本编写体验。到 Gradle 5.0 时，Kotlin DSL 已趋于稳定。

原生项目支持：Gradle 4.0+通过 cpp-plugin 和 swift-plugin 开始支持 C/C++和 Swift 项目构建，使 Gradle 真正成为跨语言构建工具。这为移动端混合开发提供了统一构建方案。

Java 模块化构建 ：Gradle 5.0 添加对 Java 9 模块系统(JPMS)的完整支持，能够处理module-info.java并执行模块路径(modulepath)而非类路径(classpath)的构建。这对采用 Java 模块化的项目至关重要。

基础设施与工具链改进

Gradle 守护进程：从 Gradle 3.0 开始，**Daemon **成为默认启用状态，长期运行的守护进程避免了重复启动 JVM 的开销，使连续构建速度提升 50%以上。

构建扫描分析 ：Gradle 4.3 引入** Build Scans **功能，通过--scan参数生成详细的构建过程分析报告，帮助开发者识别性能瓶颈和依赖问题。该功能后来成为 Gradle Enterprise 商业产品的核心组件。

版本引入	关键创新价值
3.0	implementation/api 配置隔离
3.5	引入构建缓存减少重复工作
4.0	Kotlin DSL 替代方案、C/C++/Swift 项目支持、默认并行执行
4.3	构建扫描诊断能力

补充：implementation及api的区别

配置	依赖传递性	编译隔离性	优势	适用场景
`implementation`	❌ 不传递 > 依赖仅对当前模块可见，不会泄露给其他模块。例如，模块A通过`implementation`依赖模块B，模块C依赖模块A时，模块C无法访问模块B的接口	✅ 隔离 > 编译时仅当前模块能使用该依赖，运行时依赖会打包到最终输出（如APK或AAR）	* 减少重新编译：修改`implementation`依赖时，仅需重新编译当前模块，其他依赖模块无需重新编译，显著提升大型项目的构建速度。 * 隐藏内部实现：避免依赖泄漏，降低模块间的耦合度。	默认选择，私有依赖
`api`	✅ 传递 > 依赖会传递暴露给其他模块。例如，模块A通过`api`依赖模块B，模块C依赖模块A时，模块C可直接使用模块B的接口	❌ 不隔离 > 参与编译和打包	* 构建性能较低：修改`api`依赖会导致所有依赖该模块的模块重新编译。 * 易引发冲突：若多个模块通过`api`引入同一依赖的不同版本，可能导致版本冲突（如Android Support库冲突）。	公共API或需暴露依赖的模块
`compile`	✅ 传递	❌ 不隔离		已废弃，不推荐使用

1.3.3.3 Gradle 现代架构演进（6.x-7.x 时代）

重点关注可扩展性、稳定性和大规模项目支持。

配置与执行模型革新

隔离构建逻辑 ：Gradle 6.0 引入设置插件 (Settings Plugin)和构建服务(Build Services)，允许将复杂构建逻辑封装为可复用组件，与主构建隔离执行，提高稳定性和可维护性

配置缓存 ：Gradle 6.6 引入的配置缓存通过缓存配置阶段结果（项目结构、任务图等），使后续构建跳过完整配置过程。对于大型项目，配置时间可从分钟级降至秒级，到 Gradle 7.0 时该特性已稳定

版本目录 ：Gradle 7.0 新增版本目录 (Version Catalogs)功能，通过libs.versions.toml集中管理依赖版本，解决多模块项目依赖版本不一致问题。这是依赖管理领域的重大改进

对新技术的快速适配

Java 最新支持：Gradle 6.0 开始支持 Java 14 的语言特性，7.0 添加对 Java 16 的兼容，保持与 Java 生态同步发展。每个新版本通常会在 Java 新版本发布后 3-6 个月内提供支持。

Kotlin 构建脚本增强：Gradle 7.0 对 Kotlin DSL 进行了多项改进，包括更简洁的依赖声明语法、更好的错误报告和更快的脚本编译。这使得 Kotlin 成为 Android 项目构建脚本的首选语言。

Android 构建加速：针对 Android 项目，Gradle 7.0 优化了资源处理管道，支持非传递 R 类和非压缩原生库，显著减少构建输出大小和构建时间。

用户体验与工具链完善

错误报告改进：Gradle 6.0 彻底重构了错误报告系统，提供问题上下文、修复建议和文档链接，使故障诊断效率大幅提升。错误信息可读性达到历史最佳水平。

文档搜索增强：Gradle 7.0 重新设计了官方文档，引入即时搜索和上下文敏感帮助，开发者可直接从构建错误中链接到相关文档章节。

Gradle 包装器 ：Gradle 6.0 改进了包装器(Wrapper)的依赖解析逻辑，支持通过--gradle-version参数动态选择版本，便于 CI 环境管理。

版本引入	关键创新价值
6.0	引入设置插件和构建服务，支持 Java14 语言特性
6.6	升级配置缓存
7.0	引入版本目录、kotlin 构建脚本增强、Android项目构建加速

1.3.3.4 Gradle 8.x 系列最新进展（2023-2024）

Gradle 8.x 是目前的最新稳定系列（截至 2025 年 7 月），在性能、依赖管理和多语言支持等方面继续突破边界。

性能优化达到新高度

配置缓存稳定化 ：Gradle 8.0 将配置缓存标记为稳定特性 ，推荐所有项目启用，可节省 50%-90%的配置时间。通过缓存.gradle/configuration-cache目录实现跨构建复用。

并行测试优化 ：Gradle 8.0 扩展了测试任务的并行执行能力，支持在类级别而非仅模块级别并行，结合maxParallelForks配置可充分利用多核资源。

增量编译增强 ：Gradle 8.1 改进了 Java 增量编译器，引入持续使用跟踪，即使修改常量也只需重新编译受影响文件，而非整个模块。这对包含大量常量的项目特别有益。

依赖管理持续进化

依赖解析加速：Gradle 8.0 重写了依赖解析引擎，减少内存使用和计算时间，尤其对具有复杂传递依赖的大型项目（如 Spring 生态）效果显著。

严格版本约束 ：Gradle 8.0 引入strictly和require等版本约束修饰符，精确控制依赖版本范围，避免意外升级带来的兼容性问题。

版本目录增强 ：Gradle 8.1 允许在版本目录中定义插件版本，统一管理插件和库依赖版本，避免冲突。这是对 7.0 版本目录功能的自然延伸。

语言与平台支持扩展

Java 最新版本支持：Gradle 8.0 全面支持 Java 20 特性，8.1 添加对 Java 21 的预览支持。工具链 API 简化了不同 Java 版本间的切换。

Kotlin DSL 改进 ：Gradle 8.1 为 Kotlin DSL 增加了简单赋值属性类型等实验性特性，使构建脚本更简洁。Kotlin DSL 的编译速度也比早期版本提升 3 倍以上。

CodeNarc 并行分析：针对 Groovy 项目，Gradle 8.1 默认并行运行 CodeNarc 静态分析，加速代码质量检查过程。这对大型 Groovy 代码库特别有价值。

开发者体验提升

构建扫描增强 ：Gradle 8.0 的构建扫描提供更细粒度的性能分析，可识别配置阶段耗时、依赖下载瓶颈等问题。企业版还支持跨构建趋势分析。

错误诊断改进 ：Gradle 8.0 引入问题验证器，在配置阶段早期发现潜在问题（如任务输入未声明），而非等到执行阶段报错。

文档全面更新 ：Gradle 8.x 系列伴随完整的迁移指南 和样例项目，帮助开发者从旧版本平滑过渡。每个破坏性变更都有详细说明。

版本	具体改进
8.0	配置缓存稳定化、Java 20 完整支持、依赖解析加速、严格版本约束
8.1	Java 增量编译增强、Kotlin DSL 编译加速

1.4 Gradle 项目结构

1.4.1 标准工程结构

一个典型的 Gradle 工程结构如下：

plaintext 复制代码

my-gradle-project/
├── .gradle/                # Gradle执行信息
├── .idea/                  # IDE配置信息(自动生成)
├── build/                  # 项目输出目录
│   ├── classes/            # 编译后的.class文件
│   └── resources/          # 处理后的资源文件
├── src/                    # 项目源码
│   ├── main/               # 主代码
│   │   ├── java/           # Java源代码
│   │   └── resources/      # 主资源文件
│   └── test/               # 测试代码
│       ├── java/           # 测试Java代码
│       └── resources/      # 测试资源文件
├── build.gradle            # 当前模块的构建配置
└── settings.gradle         # 项目全局配置

1.4.2 核心配置文件

settings.gradle

Gradle 多项目构建的全局配置文件，定义包含哪些子项目 ，配置项目层次结构和名称

groovy 复制代码

rootProject.name = 'my-root-project'  # 设置根项目名称
include 'api', 'web', 'shared'        # 包含子项目

build.gradle

项目的主要构建脚本，应用插件 、配置项目 、定义依赖等

groovy 复制代码

plugins {
    id 'java'  # 应用Java插件
}

group = 'com.example'
version = '1.0.0'

repositories {
    mavenCentral()  # 使用Maven中央仓库
}

dependencies {
    implementation 'org.springframework:spring-core:5.3.9'
    testImplementation 'junit:junit:4.13.2'
}

task customTask {
    doLast {
        println 'Hello from custom task!'
    }
}

gradle.properties

配置 Gradle 属性和项目常量，可以设置** JVM 参数、全局变量**等

properties 复制代码

org.gradle.jvmargs=-Xmx2g
versionCode=1
versionName=1.0.0

gradle-wrapper.properties

配置 Gradle Wrapper 使用的 Gradle 版本

properties 复制代码

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-7.4.2-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

2. 生命周期

Gradle 的构建过程遵循严格的生命周期模型，分为三个主要阶段：初始化阶段、配置阶段和执行阶段。这三个阶段按顺序执行，每个阶段都有特定的职责和回调机制。

2.1 Gradle 构建生命周期图示

2.1 初始化阶段（Initialization）

初始化阶段是 Gradle 构建的第一个阶段，主要完成以下工作：

确定项目结构 ：Gradle 根据settings.gradle或settings.gradle.kts文件初始化构建环境，确定项目结构和参与构建的模块

创建项目层次 ：在多项目构建中，Gradle 根据settings.gradle文件定义的项目层次结构，初始化所有子项目

创建 Project 实例：为每个参与构建的项目创建 Project 对象

执行初始化脚本 ：加载全局初始化脚本（~/.gradle/init.gradle）和项目初始化脚本（project/init.gradle）

初始化阶段的关键回调：

groovy 复制代码

gradle.settingsEvaluated {
    println 'settings.gradle脚本执行完毕' 
}
gradle.projectsLoaded {
    println '初始化阶段结束，所有Project实例已创建' 
}

初始化阶段完成后，Gradle 就知道了要构建哪些项目以及它们之间的关系。

2.2 配置阶段（Configuration）

配置阶段是 Gradle 构建的第二个阶段，主要完成以下工作：

解析构建脚本 ：Gradle 解析项目的build.gradle或build.gradle.kts文件，应用插件、配置依赖关系和任务

应用插件：Gradle 应用构建脚本中的插件，插件可以添加任务、扩展项目对象和定义构建逻辑

配置任务：Gradle 配置构建脚本中的任务，包括设置任务属性和依赖关系

构建任务图：实现 task 任务的拓扑图，这个图是一个有向无环图(DAG)，防止任务执行进入死循环

配置阶段的关键回调：

groovy 复制代码

gradle.beforeProject { project ->
    println "${project.name}配置前" 
}
gradle.afterProject { project ->
    println "${project.name}配置完成" 
}
gradle.projectsEvaluated {
    println '所有项目评估完成（配置阶段结束）' 
}
gradle.taskGraph.whenReady {
    println 'task拓扑图构造完毕' 
}

2.3 执行阶段（Execution）

执行阶段是 Gradle 构建的最后一个阶段，主要完成以下工作：

任务选择：Gradle 根据构建命令和项目配置确定要执行的任务集，支持单任务和多任务执行

任务执行：Gradle 按依赖关系顺序执行任务，任务可以是插件提供的或用户自定义的，执行时运行其代码块中的逻辑

增量构建：Gradle 通过检查文件变化和任务输出，智能跳过未变化的任务，提高构建效率

执行阶段的关键回调：

groovy 复制代码

gradle.taskGraph.beforeTask { task ->
    println "准备执行任务${task.name}" 
}
gradle.taskGraph.afterTask { task ->
    println "任务${task.name}执行完成" 
}
gradle.buildFinished {
    println '构建过程结束' 
}

2.4 总结

阶段	动作	核心产物
初始化	确定哪些项目参与构建，为每个项目创建 Project 实例	`Settings` 对象、`Project` 实例树
配置	解析构建脚本，配置任务和依赖关系，构建任务图	任务 DAG、DSL 配置、插件扩展
执行	按照任务依赖关系执行任务，支持增量构建	编译输出、打包产物、测试报告

3. 性能优化与调试技巧

3.1 性能优化

3.1.1 构建扫描

作用：生成详细的构建性能报告

bash 复制代码

./gradlew build --scan # 自动上传报告至 scans.gradle.com

3.1.2 分析构建

作用：生成本地 HTML 报告，展示各阶段（初始化、配置、执行）耗时。

输出路径：build/reports/profile/

bash 复制代码

./gradlew assemble --profile

3.2 调试技巧

3.2.1 依赖冲突

查看全量依赖

bash 复制代码

./gradlew dependencies

检查特定依赖冲突

bash 复制代码

./gradlew dependencyInsight --dependency commons-logging

适用场景：发现 androidx.core:core-ktx 存在多个版本（如 1.6.0 和 1.8.0），通过 force() 强制统一版本

3.2.2 构建失败调试

增加日志详细程度

bash 复制代码

./gradlew build --info     # 基础日志
./gradlew build --debug    # 详细日志（含任务输入输出）

堆栈跟踪

bash 复制代码

./gradlew build --stacktrace      # 简化堆栈
./gradlew build --full-stacktrace # 完整堆栈

适用场景：插件兼容性错误（如 AGP 与 Kotlin 版本不匹配），通过日志定位到具体报错行

3.2.3 缓存问题

清理缓存

bash 复制代码

./gradlew clean          # 清理项目 build/ 目录
rm -rf ~/.gradle/caches/ # 清理全局缓存（谨慎使用）

适用场景：修改 ProGuard 规则后未生效，清理缓存后重新构建

4. Gradle Task

Gradle Task 是 Gradle 构建系统中的核心概念之一，它代表了构建过程中的一个原子性操作，例如编译代码、打包应用程序、运行测试、生成文档等。Gradle 作为一个强大的项目自动化构建工具，其灵活性和可扩展性很大程度上来源于 Task 的设计和实现。在 Gradle 中，所有的构建工作都是由一个或多个 Task 组合完成的。

以下是浏览器项目中 Gradle Task 的运用，在编译前进行 release 版本的 checkstyle：

4.1 Gradle 任务执行模型

Gradle 的任务执行模型基于有向无环图(DAG)，这是理解任务如何执行的核心。

阶段 1：初始化
- 检测 settings.gradle(.kts) 文件。
- 创建一个 Settings 实例。
- 评估设置文件，以确定哪些项目（和包含的构建）构成了本次构建。
- 为每个项目创建一个 Project 实例。
阶段 2：配置
- 评估所有参与构建的项目的构建脚本 build.gradle(.kts)。
- 为所请求的**任务**创建任务图（task graph）。
阶段 3：执行
- 调度并执行选定的任务。
- 任务之间的依赖关系决定了执行顺序。
- 任务的执行可以并行进行。

4.2 任务创建与注册

Gradle 提供了两种创建任务的方式：

create：立即创建任务

groovy 复制代码

tasks.create('hello') {
    doLast { println 'greeting' }
}

register：注册一个任务提供者(懒加载)

groovy 复制代码

tasks.register('hello') {
    doLast { println 'greeting' }
}

区别：

register延迟到实际需要时才创建任务，是官方推荐的方式（称为"task configuration avoidance"）
create会立即创建和配置任务，可能在配置阶段创建不会被使用的任务

4.3 任务依赖关系

Gradle 任务之间可以通过多种方式建立依赖关系：

dependsOn：强依赖，指定任务必须在哪些任务之后执行

groovy 复制代码

taskB.dependsOn taskA

finalizedBy：终结器任务，指定任务执行后必须执行的任务

groovy 复制代码

taskB.finalizedBy taskC

mustRunAfter/shouldRunAfter：指定执行顺序（非强依赖）

groovy 复制代码

taskB.mustRunAfter taskA

通过输入输出建立隐式依赖：

groovy 复制代码

taskA {
    outputs.file("$buildDir/output.txt")
}
taskB {
    inputs.files(taskA.outputs)
}

4.4 任务执行图(Task Graph)构建流程

任务收集：在配置阶段完成后，所有任务都被添加到 Project 的 TaskContainer 中

入口任务 ：根据用户指定的任务（如gradle build中的build）作为起点

依赖解析：从入口任务开始，递归解析所有依赖任务

拓扑排序：根据依赖关系对任务进行拓扑排序，确定执行顺序

执行计划：生成最终的执行计划(ExecutionPlan)

考虑以下任务定义：

groovy 复制代码

task grandpa {
    doLast { println 'grandpa' }
}
task father(dependsOn: grandpa) {
    doLast { println 'father' }
}
task mother {
    doLast { println 'mother' }
}
task child(dependsOn: [father, mother]) {
    doLast { println 'child' }
}
father.mustRunAfter mother

执行gradle child时，任务图如下：

plaintext 复制代码

:child
+--- :father
|    \--- :grandpa
\--- :mother

执行顺序为：mother → grandpa → father → child

5. Gradle Version Catalog

从 Gradle 7.x 开始，Gradle 的依赖版本控制采用全新的 Version Catalog 功能（版本目录），旨在帮助开发者更高效地管理多模块项目中的依赖项和插件版本。它提供了一个集中的、可维护的依赖管理机制，避免了传统方式中对版本号的硬编码问题，从而提升了构建脚本的可读性和可维护性。

5.1 Gradle Version Catalog 的基本概念

Gradle Version Catalog 是一种基于 TOML（Tom's Obvious, Minimal Language）格式的配置文件，通常命名为 libs.versions.toml，并放置在项目的 gradle 目录中。该文件允许开发者将依赖项的版本、库坐标、插件定义以及依赖包（bundles）统一管理，从而实现依赖项的集中化管理。

TOML 是一种轻量级的配置文件格式，具有良好的可读性和简洁的语法，非常适合用于版本目录的定义。通过 libs.versions.toml 文件，开发者可以定义以下四个主要部分：

[versions] ：声明版本号，供其他部分引用。
[libraries] ：定义依赖库的坐标（group、name 和版本引用）。
[bundles] ：定义一组依赖项的集合，便于一次引入多个库。
[plugins] ：声明插件的 ID 和版本。

这种结构化的管理方式使得项目依赖关系更加清晰，也便于团队协作和版本升级。

5.2 Gradle Version Catalog 的优势

使用 Gradle Version Catalog 有以下几个显著的优势：

集中管理依赖版本 ：所有依赖项的版本都可以在一个文件中定义，避免了在多个 build.gradle 文件中重复定义版本号的问题。
版本升级更简单 ：当需要升级某个依赖项的版本时，只需修改 libs.versions.toml 文件中的版本号，而无需逐个修改各个模块的构建文件。
提高构建脚本的可读性：通过别名和结构化配置，构建脚本中的依赖项变得更加简洁和易读。
支持依赖集合（Bundles）：可以将多个依赖项打包成一个 bundle，简化了对多个库的引用。
插件管理 ：除了依赖项，还可以在 libs.versions.toml 中定义插件的版本，从而统一管理插件的使用。

5.3 Gradle Version Catalog 的配置与使用

创建版本目录文件

首先，需要在项目的根目录下的 gradle 文件夹中创建 libs.versions.toml 文件。Gradle 默认会查找该文件，因此建议使用默认名称，避免不必要的配置更改。

配置 TOML 文件

在 libs.versions.toml 文件中，可以定义如下内容：

版本号：

toml 复制代码

[versions]
jsch = "0.1.55"
kotlin = "2.0.0"

依赖库：

toml 复制代码

[libraries]
jcraft-jsch = { group = "com.jcraft", name = "jsch", version.ref = "jsch" }
androidx-core-ktx = { module = "androidx.core:core-ktx", version.ref = "androidx-corektx" }
kotlin-stdlib = { group = "org.jetbrains.kotlin", name = "kotlin-stdlib", version.ref = "kotlin" }

依赖包（Bundles）：

toml 复制代码

[bundles]
androidx = ["androidx-core-ktx", "kotlin-stdlib"]

插件：

toml 复制代码

[plugins]
android-application = { id = "com.android.application", version.ref = "7.2.1" }

在构建脚本中使用

在 build.gradle 或 build.gradle.kts 文件中，可以通过别名引用依赖项。例如，使用 libs.jcraft.jsch 来引用 com.jcraft:jsch：

groovy 复制代码

dependencies {
    implementation libs.androidx.core.ktx
}

如果需要使用依赖包，可以直接引用 bundle 名称：

groovy 复制代码

dependencies {
    implementation libs.bundles.androidx
}

如果是引用 BOM 包，则可以通过以下方式引入：

kotlin 复制代码

/// kts写法
dependencies {
    // Compose
    val composeBom = platform(libs.androidx.compose.bom)
    implementation(composeBom)
}

如果想要引用子 module 的的依赖包，也可以使用 Version Catalog 进行管理，但需要提前打开一个 preview feature：

kotlin 复制代码

/// settings.gradle.kts
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")

/// app/build.gradle.kts
dependencies {
    implementation(projects.core.data)
}

minSdk、targetSdk、compileSdk 都是可以使用 Version Catalog 进行管理：

kotlin 复制代码

android {
    compileSdk = libs.versions.compileSdk.get().toInt()
    defaultConfig {
        minSdk = libs.versions.minSdk.get().toInt()
        targetSdk = libs.versions.targetSdk.get().toInt()
    }
}

对于插件的使用，可以使用 plugins 块：

groovy 复制代码

plugins {
    alias(libs.plugins.android.application)
}

这种方式不仅简化了依赖声明，还使得版本管理更加直观和集中。

同时，使用 Version Catalog 后可以直接在 IDE 中点击跳转到对应的依赖位置，相比于自建的版本依赖管理可快速定位并修改版本。

点击可调转到

对应的 TOML 页面

5.4 Gradle Version Catalog 的适用场景

Gradle Version Catalog 特别适合以下几种场景：

多模块项目 ：在拥有多个模块的项目中，依赖项和插件版本的管理变得复杂。Version Catalog 提供了一个集中管理的解决方案，使得版本升级和维护更加简单。
团队协作 ：当多个开发者共同维护一个项目时，统一的依赖管理可以减少版本冲突和重复工作。
大型项目 ：对于依赖项较多的项目，Version Catalog 可以有效减少构建脚本的冗余代码，提高可读性。
插件管理 ：对于需要使用多个插件的项目，Version Catalog 可以统一管理插件的版本，简化插件的声明过程。

5.5 Gradle Version Catalog 的历史演进

Gradle Version Catalog 最初在 Gradle 7.0 版本中引入，并在 Gradle 7.4 版本中变得稳定。随着 Gradle 8.x 版本的发布，Version Catalog 的功能得到了进一步增强，例如在 Kotlin DSL 脚本插件中支持版本目录。如今，Gradle Version Catalog 已经成为现代 Gradle 项目中不可或缺的一部分，尤其在 Android 开发中得到了广泛应用。

5.6 Gradle Version Catalog 的最佳实践

统一命名规范 ：为了提高可读性，建议为依赖项和插件定义清晰的命名规范，例如 libs.plugins.android.application。
避免硬编码版本号 ：尽量将所有依赖项的版本号定义在 libs.versions.toml 文件中，避免在构建脚本中直接使用版本号。
定期更新版本目录 ：随着项目的演进，依赖项和插件的版本可能会发生变化，建议定期更新版本目录文件，确保所有模块使用最新的依赖版本。
使用依赖包简化引入过程 ：对于经常一起使用的依赖项，可以将它们打包成一个 bundle，便于一次引入多个库。

5.7 Gradle Version Catalog 的局限性

尽管 Gradle Version Catalog 提供了诸多便利，但也存在一些局限性：

版本目录文件的维护成本 ：随着项目规模的扩大，版本目录文件可能会变得臃肿，需要良好的组织和维护。
不适用于所有项目 ：对于小型项目或依赖项较少的项目，Version Catalog 的优势可能不明显，反而会增加配置复杂度。

5.8 Gradle Version Catalog 的未来展望

随着 Gradle 版本的不断演进，Version Catalog 的功能也在不断增强。例如，在 Gradle 8.5 版本中，Kotlin DSL 的性能得到了提升，并进一步优化了 Version Catalog 的使用体验。未来，Gradle 可能会引入更多与 Version Catalog 相关的功能，例如支持更复杂的依赖管理策略、提供更好的错误提示机制等。

总的来说，Gradle Version Catalog 是一个强大的工具，能够显著简化依赖管理和插件管理，尤其适合多模块和大型项目。通过合理使用 Version Catalog，开发者可以提升构建脚本的可维护性和可读性，同时减少版本冲突和重复配置的问题

6. Gradle Plugin

6.1 Gradle Plugin 的概念

Gradle Plugin 是用于扩展 Gradle 构建工具功能的插件，它可以添加新的任务、配置或改变现有任务的行为。例如，Gradle 本身并没有提供编译打包等具体功能，它只是一个负责定义流程和规则的框架，具体的构建工作都是由插件来完成的，比如编译 Java 用 Java 插件，编译 Kotlin 用 Kotlin 插件。

6.2 Gradle Plugin 的作用

6.2.1 模块化与复用性

**功能封装：**将构建逻辑（如编译、打包、代码生成等）封装为独立插件，避免重复编写脚本。

例如，Android 项目的 com.android.application 插件封装了资源处理、DEX 转换等复杂流程。

groovy 复制代码

// 自定义插件类，封装资源处理和DEX转换逻辑
class MyAndroidPlugin implements Plugin<Project> {
    void apply(Project project) {
        project.android {
            compileSdkVersion 33
            defaultConfig {
                minSdkVersion 21
                targetSdkVersion 33
            }
        }
    }
}
// 应用插件
apply plugin: MyAndroidPlugin

**跨项目复用：**公共功能（如代码风格检查、依赖管理）可通过插件共享，减少"复制粘贴"式代码。

例如，团队可自定义代码质量检查插件，统一应用到所有项目中

kotlin 复制代码

// QualityConventionPlugin.kt
class QualityConventionPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        // 1. 添加扩展配置（允许项目自定义规则路径）
        val extension = project.extensions.create<QualityExtension>("quality", project)

        // 2. 应用检查工具插件
        project.pluginManager.apply("checkstyle")
        project.pluginManager.apply("pmd")
        project.pluginManager.apply("com.github.spotbugs")

        // 3. 统一配置规则
        project.configureCheckstyle(extension)
        project.configurePmd(extension)
        project.configureSpotBugs(extension)
    }

    private fun Project.configureCheckstyle(ext: QualityExtension) {
        checkstyle {
            toolVersion = "10.3.2"
            configFile = ext.checkstyleRules 
                ?: file("${rootDir}/config/checkstyle/team-rules.xml")  // 默认规则
            isIgnoreFailures = false
        }
        tasks.named("checkstyleMain") {
            reports { xml.required.set(true) }
        }
    }
}
...

6.2.2 扩展构建能力

**填补原生功能空白：**Gradle 原生不支持某些特定技术栈（如 Android 开发、Kotlin 多平台），需通过插件扩展。例如：
- Android Gradle Plugin (AGP)：提供 android{} DSL 配置，处理APK打包、资源压缩等 Android 特有任务
- Kotlin 插件：支持 Kotlin 代码编译与跨平台项目构建
**集成第三方工具：**插件可无缝集成静态分析工具（如 SonarQube）、性能监控工具（如 Matrix）等。

6.2.3 标准化构建流程

统一配置管理：通过插件强制约定构建规则。例如：

AGP 强制要求 compileSdkVersion 等关键参数遵循约定规则，确保编译环境一致性

参数	作用	AGP 的强制行为
`buildToolsVersion`	指定构建工具链版本（如 `aapt`、`d8`）	AGP 7.0+ 自动选择匹配版本，无需手动配置。
`targetSdkVersion`	指定应用运行时的兼容性级别	必须 ≤ `compileSdkVersion`，否则构建失败。
`minSdkVersion`	定义应用支持的最低 Android 版本	必须 ≤ `targetSdkVersion`，否则报错。
`ndkVersion`	控制原生代码编译的 NDK 工具链版本	AGP 4.0+ 支持自动下载，或强制指定合法版本

自定义插件可统一代码混淆规则或代码生成模板

kotlin 复制代码

// 自定义插件代码
class ObfuscationPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.android.buildTypes.all {
            proguardFiles(project.rootProject.file("team-rules.pro"))
        }
    }
}

**生命周期钩子：**插件可在 Gradle 生命周期的特定阶段（如配置阶段）插入逻辑。
- 例如，在 afterEvaluate 回调中动态修改 Task 依赖关系
groovy 复制代码
```
project.afterEvaluate {
    tasks.named("assembleDebug") {
        dependsOn(":lint")  // 确保构建前执行代码检查
    }
}
```

6.2.4 支持高级技术场景

**自动化复杂操作：**通过 Transform API （Gradle8.0+被移除）或AsmClassVisitorFactory修改编译后的字节码，实现以下功能：
- 路由框架插件（如 ARouter）：在编译时扫描注解并生成路由表，避免运行时反射
- 无痕埋点插件：自动在点击事件中插入埋点代码，减少手动编码
groovy 复制代码
```
//修改字节码前
button.setOnClickListener(v -> {
    startActivity(new Intent(this, DetailActivity.class));
});

//修改字节码后
button.setOnClickListener(v -> {
    startActivity(new Intent(this, DetailActivity.class));
    TcStatInterface.onClick(v); // 自动插入
});
```
- 性能监控：插入方法耗时统计代码（如滴滴的 DoKit）
- 稳定性增强：替换系统 API 调用为安全封装（如 SafeToast 替换 Toast）
**包体积优化：**插件可内联常量、删除无用资源（如字节跳动的 ByteX 插件）
**增量构建优化：**插件可识别输入/输出变化，跳过未修改的任务

6.3 实现方式

6.3.1 方法一：build.gradle

脚本插件通常是 Groovy 脚本，可嵌入到构建脚本中，它们定义了任务和依赖项。特点：

直接在构建文件(build.gradle)中编写插件代码

自动编译，无需执行其他操作

生成的插件对外部不可见，只能在当前项目使用

kotlin 复制代码

class MyGradlePlugin : Plugin<Project> {
    override fun apply(target: Project) {
        println("Hello, Gradle!")
    }
}

apply<MyGradlePlugin>()

6.3.2 方法二：buildSrc

在项目根目录创建 buildSrc 目录

该目录中的代码会被 Gradle 自动编译并添加到构建脚本的 classpath

适合没有复用性或调试阶段的插件

6.3.2.1 新建文件及目录

尽量不要使用 android studio 中自带的创建模块的功能，可能会有些问题。

新建 buildSrc 文件夹，目录层级如下

kotlin 复制代码

buildSrc/
  ├── build.gradle.kts (或 build.gradle)
  └── src/
      └── main/
          ├── groovy/ (或 java/)
          └── resources/
              └── META-INF/
                  └── gradle-plugins/
                      └── com.example.plugin.properties

6.3.2.2 配置 buildSrc/build.gradle 文件

groovy 复制代码

plugins {
    id 'groovy'
    id 'maven-publish'
}

dependencies {
    implementation gradleApi()      // 引入 Gradle API
    implementation localGroovy()    // Groovy SDK
}

repositories {
    mavenCentral()
    google()
}

6.3.2.3 编写插件类

groovy 复制代码

package com.example

import org.gradle.api.Plugin
import org.gradle.api.Project

class MyCustomPlugin implements Plugin<Project> {
    void apply(Project project) {
        project.tasks.register('customTask') {
            doLast {
                println("Hello from Custom Plugin!")
            }
        }
    }
}

6.3.2.4 声明插件 ID

方式一：在 resources/META-INF/gradle-plugin 下创建.properties 文件

groovy 复制代码

implementation-class=com.example.MyCustomPlugin

方式二：通过 gradlePlugin 块，在插件的 build.gradle 文件中创建

groovy 复制代码

gradlePlugin {
    plugins {
        register("myPlugin") {
            id = "com.example.plugin" // 插件 ID
            implementationClass = "com.example.MyCustomPlugin" // 全类名
        }
    }
}

6.3.2.5 使用

groovy 复制代码

//在目标project的build.gradle文件下

// 方式一：传统语法
apply plugin: 'com.example.plugin'

// 方式二：plugins DSL（需兼容配置）
plugins {
    id 'com.example.plugin'
}

6.3.2.6 执行任务

bash 复制代码

./gradlew customTask

6.3.3 方法三：独立项目

创建单独的项目开发插件

将插件打包为 JAR 文件发布到仓库

可在多个项目间复用，是推荐的插件开发方式

6.3.3.1 新建模块

6.3.3.2 构建目录层级

kotlin 复制代码

src/main
├── groovy    # 插件源码目录
└── resources/META-INF/gradle-plugins  # 插件声明文件

6.3.3.3 配置插件类

groovy 复制代码

package com.example

import org.gradle.api.Plugin
import org.gradle.api.Project

class MyCustomPlugin implements Plugin<Project> {
    void apply(Project project) {
        project.tasks.register('customTask') {
            doLast {
                println("Hello from Custom Plugin!")
            }
        }
    }
}

6.3.3.4 声明插件 ID

方式一：在 resources/META-INF/gradle-plugin 下创建.properties 文件

groovy 复制代码

implementation-class=com.example.MyCustomPlugin

方式二：通过 gradlePlugin 块，在插件的 build.gradle 文件中创建

groovy 复制代码

gradlePlugin {
    plugins {
        register("myPlugin") {
            id = "com.example.plugin" // 插件 ID
            implementationClass = "com.example.MyCustomPlugin" // 全类名
        }
    }
}

6.3.3.5 插件发布

在自定义 gradle 模块的 build.gradle 中添加如下信息

groovy 复制代码

plugins {
    id 'groovy'
    id 'maven-publish'
}

dependencies {
    implementation gradleApi()           // 依赖Gradle API
    implementation localGroovy()         // Groovy SDK
}

// 发布到本地Maven仓库
publishing {
    publications {
        mavenJava(MavenPublication) {
            groupId = 'com.example.plugin'
            artifactId = 'com.example.plugin.gradle.plugin'
            version = '1.0.0'
            from components.java
        }
    }
    repositories {
        maven { url = uri("../myPlugin/repo") }  // 本地仓库路径
    }
}

Gradle 要求插件 ID 与 Maven 坐标的转换格式：

plugin.id → groupId:plugin.id.gradle.plugin:version

因此如后续在 plugin 模块通过 id 的方式引用插件，需要注意 artifactId 的命名

6.3.3.6 发布插件

bash 复制代码

//执行Gradle任务 生成的插件将存储在指定的目录下
./gradlew publish

6.3.3.7 在目标模块 setting.gradle 中插入仓库的地址

groovy 复制代码

pluginManagement {
    repositories {
        google {
            ...
        }
        maven {
            url uri("file:///D:/ASFiles/GradleLearning/myPlugin/repo")
        }
        ...
    }
    ...
}

6.3.3.8 在目标模块中使用

groovy 复制代码

//方案1：使用apply plugin
buildscript {
    repositories {
        maven { url = uri("../myPlugin/repo") }
    }
    dependencies {
        classpath 'com.example:myplugin:1.0.0'
    }
}
apply plugin: 'com.example.myplugin'

//方案2：使用plugin id
plugins {
    id 'com.example.plugin'
}