213. Gradle 构建工具入门

一、Gradle 简介

Gradle 构建工具入门

什么是 Gradle？

Gradle 是一个基于 Groovy 和 Kotlin DSL（领域特定语言）的开源构建自动化工具，主要用于 Java、Kotlin、Android 等项目的构建、测试、部署等任务。它结合了 Apache Ant 的灵活性和 Apache Maven 的约定优于配置（Convention over Configuration）理念，同时引入了强大的依赖管理和增量构建机制。

核心特点

1. 声明式构建脚本
   使用 Groovy 或 Kotlin DSL 编写脚本，语法简洁直观。例如：

   plugins {
       id 'java' // 应用 Java 插件
   }
   dependencies {
       implementation 'org.springframework:spring-core:5.3.0' // 声明依赖
   }
   

2. 增量构建（Incremental Build）
   仅重新编译修改过的文件，大幅提升构建速度。

3. 多项目支持
   支持模块化项目，通过 include 和 settings.gradle 管理子项目。

4. 依赖管理
   兼容 Maven 和 Ivy 仓库，支持传递性依赖和冲突解决。

5. 插件化架构
   通过插件扩展功能（如 java、application、android 等）。

使用场景

• Java/Kotlin 项目：编译、打包、生成 JAR/WAR 文件。
• Android 开发：官方推荐的构建工具。
• 持续集成（CI）：与 Jenkins、TeamCity 等工具集成。
• 多语言项目：支持 C++、Python 等（通过插件）。

常见误区

1. Groovy vs. Kotlin DSL
   Groovy DSL 更成熟，Kotlin DSL 类型安全但学习曲线略高。初学者建议从 Groovy 开始。

2. 依赖冲突
   多个依赖库版本不一致时，需通过 resolutionStrategy 强制指定版本：

   configurations.all {
       resolutionStrategy.force 'com.google.guava:guava:30.1.1-jre'
   }
   

3. 构建缓存
   默认开启的缓存可能导致问题，可通过 --no-build-cache 禁用。

示例：简单 Java 项目

1. build.gradle 文件：

   plugins {
       id 'java'
   }
   repositories {
       mavenCentral() // 使用 Maven 中央仓库
   }
   dependencies {
       testImplementation 'junit:junit:4.13.2' // 测试依赖
   }
   

2. 常用命令：

   • gradle build：编译并打包。
   • gradle test：运行测试。
   • gradle clean：清理构建目录。

注意事项

• Gradle Wrapper：推荐使用 gradlew（Wrapper）保证团队环境一致。
• 性能调优：通过 org.gradle.jvmargs 调整 JVM 内存参数。

---

Gradle 的特点与优势

1. 基于 Groovy 和 Kotlin 的 DSL

Gradle 使用 领域特定语言（DSL） 进行构建脚本编写，支持 Groovy 和 Kotlin 两种语法：

• Groovy DSL：简洁灵活，适合快速编写构建逻辑。
• Kotlin DSL：类型安全，IDE 支持更好，适合大型项目。

示例（Groovy DSL）：

plugins {
    id 'java'
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web:2.7.0'
}

2. 增量构建（Incremental Build）

Gradle 通过 任务输入/输出分析 实现增量构建：

• 仅重新执行受影响的任务，避免重复工作。
• 显著提升构建速度，尤其适合大型项目。

3. 依赖管理强大

• 支持多种仓库：Maven、Ivy、本地仓库等。
• 依赖冲突解决：智能选择版本，避免冲突。
• 传递性依赖：自动处理依赖的依赖。

示例：

dependencies {
    implementation('com.google.guava:guava:31.1-jre') {
        exclude group: 'org.checkerframework', module: 'checker-qual'
    }
}

4. 多项目构建支持

• 子项目（subprojects）：支持模块化构建。
• 依赖传递：项目间依赖管理清晰。
• 配置共享：通过 allprojects 或 subprojects 统一配置。

示例：

// 根项目 build.gradle
allprojects {
    repositories {
        mavenCentral()
    }
}

// 子项目 build.gradle
dependencies {
    implementation project(':core-module')
}

5. 高性能

• 守护进程（Daemon）：减少 JVM 启动开销。
• 并行执行：多任务并行构建。
• 构建缓存：复用历史构建结果。

6. 插件生态系统

• 官方插件：Java、Android、Spring Boot 等。
• 社区插件：覆盖 Docker、Kubernetes、Protobuf 等场景。
• 自定义插件：支持扩展构建逻辑。

示例（应用 Spring Boot 插件）：

plugins {
    id 'org.springframework.boot' version '2.7.0'
}

7. 与 CI/CD 集成

• 命令行友好：支持 gradlew（Wrapper）确保环境一致。
• Jenkins/GitLab CI 集成：通过脚本触发构建。
• 生成构建报告：测试覆盖率、依赖分析等。

8. 灵活性

• 自定义任务：支持编写任意构建逻辑。
• Hook 点：通过 doFirst、doLast 干预任务执行。
• 条件化构建：根据环境动态调整配置。

示例（自定义任务）：

task deployToTest(type: Copy) {
    from 'build/libs'
    into '/opt/test-server'
    dependsOn build
}

9. 跨平台支持

• Windows/macOS/Linux 全平台兼容。
• 与 JDK 版本解耦：通过 Wrapper 指定 Gradle 版本。

10. 社区与生态

• Android 官方构建工具：Google 强力支持。
• 企业级应用：Netflix、LinkedIn 等公司采用。

---

Gradle 与其他构建工具（Maven、Ant）的比较

1. 核心设计理念

• Gradle：基于 Groovy/Kotlin DSL 的声明式构建工具，结合了 约定优于配置 和 灵活性。支持增量构建和任务依赖管理。
• Maven：基于 XML 的严格约定优于配置模型，强调 标准化生命周期 和 依赖管理。
• Ant：基于 XML 的过程式脚本工具，无内置约定，完全依赖用户手动定义构建步骤。

2. 构建脚本语言

• Gradle：使用 Groovy 或 Kotlin DSL，代码简洁且可编程性强。

  // 示例：定义一个任务
  task hello {
      doLast {
          println 'Hello, Gradle!'
      }
  }
  

• Maven：使用 XML，冗长但结构化。

  <!-- 示例：定义插件 -->
  <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.8.1</version>
  </plugin>
  

• Ant：使用 XML，需手动编写任务链。

  <!-- 示例：编译Java代码 -->
  <target name="compile">
      <javac srcdir="src" destdir="build"/>
  </target>
  

3. 依赖管理

• Gradle：兼容 Maven/Ivy 仓库，支持动态版本（如 1.0.+）和细粒度排除规则。

  dependencies {
      implementation 'org.springframework:spring-core:5.3.0'
      testImplementation 'junit:junit:4.13'
  }
  

• Maven：通过 <dependencies> 管理，依赖范围（如 compile、test）明确。

  <dependencies>
      <dependency>
          <groupId>junit</groupId>
          <artifactId>junit</artifactId>
          <version>4.13</version>
          <scope>test</scope>
      </dependency>
  </dependencies>
  

• Ant：无内置依赖管理，需手动下载或通过 Ivy 扩展实现。

4. 性能对比

• Gradle：
  • 增量构建：仅重新执行变化的任务。
  • 构建缓存：可复用历史构建结果。
  • Daemon 进程：减少 JVM 启动开销。
• Maven：
  • 生命周期阶段固定，灵活性低，但适合标准化流程。
  • 无增量编译（需插件支持）。
• Ant：
  • 性能完全依赖脚本设计，易因冗余任务降低效率。

5. 适用场景

• Gradle：
  • 需要 高度定制化 的构建流程（如多模块、跨语言项目）。
  • 追求 构建速度 和 可维护性 的大型项目（如 Android 官方推荐）。
• Maven：
  • 传统 Java 企业项目，强调 标准化 和 稳定性。
  • 需要与 CI/CD 工具（如 Jenkins）深度集成。
• Ant：
  • 遗留系统维护或 简单任务自动化（如文件操作）。
  • 需要完全控制构建步骤的场景。

6. 常见误区

• Gradle：
  • 误认为 Groovy/Kotlin 脚本难以调试（实际支持 IDE 断点）。
  • 过度自定义导致脚本复杂化（应优先使用标准插件）。
• Maven：
  • 误用 <executions> 配置插件，导致构建时间过长。
  • 忽略 <dependencyManagement> 的版本统一作用。
• Ant：
  • 手动管理依赖易引发版本冲突。
  • 缺乏生命周期导致脚本冗余。

7. 迁移建议

• Ant → Gradle：利用 Gradle 的 ant.importBuild 逐步替换。
• Maven → Gradle：通过 gradle init 自动转换 pom.xml，再优化 DSL 逻辑。

---

Gradle 的应用场景

1. 构建 Java 项目

Gradle 最初是为 Java 项目设计的构建工具，能够高效地编译、测试、打包和发布 Java 应用。它支持多模块项目，并能与 Maven 和 Ivy 仓库无缝集成。

plugins {
    id 'java'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web:2.5.0'
    testImplementation 'junit:junit:4.13'
}

2. Android 开发

Gradle 是 Android 官方推荐的构建工具，用于配置 Android 应用的编译、打包和签名流程。通过 Android Gradle 插件（AGP），开发者可以灵活定制构建变体（如 debug/release）。

android {
    compileSdkVersion 30
    defaultConfig {
        applicationId "com.example.app"
        minSdkVersion 21
    }
}

3. 多语言项目支持

通过插件支持 Kotlin、Groovy、C++ 等语言：

• Kotlin 项目：id 'org.jetbrains.kotlin.jvm'
• C++ 项目：id 'cpp-application'

4. 持续集成（CI/CD）

Gradle 脚本可集成到 Jenkins、GitLab CI 等工具中，实现自动化构建、测试和部署：

./gradlew clean build publish

5. 复杂构建逻辑

适用于需要动态决策的构建场景，例如：

• 根据环境变量选择依赖版本
• 自定义任务链（如先生成代码再编译）

task deployProd {
    doLast {
        if (project.hasProperty('release')) {
            println "Deploying to production"
        }
    }
}

6. 微服务架构

在多模块微服务项目中，Gradle 能高效管理子模块的依赖关系和构建顺序：

// settings.gradle
include 'user-service', 'order-service', 'gateway'

7. 插件开发

支持开发自定义 Gradle 插件，复用构建逻辑（如统一代码风格检查）。

8. 性能敏感场景

利用增量构建（Incremental Build）和构建缓存（Build Cache）加速大型项目构建。

注意事项

• 学习曲线较陡峭，适合中大型项目
• 灵活性强，但需避免过度复杂的脚本设计
• 建议结合 Gradle Wrapper 保证环境一致性

---

二、安装与配置

下载 Gradle

官方下载渠道

1. 官网下载：访问 Gradle 官方网站 下载最新版本或历史版本。
2. 版本选择：
   • 稳定版（Stable）：推荐生产环境使用。
   • 候选版（Release Candidate）：测试新特性。
   • ** nightly 构建版**：开发者尝鲜（不稳定）。

下载文件类型

• 二进制包（Binary-only）：仅包含运行时（推荐大多数用户）。
• 完整包（Complete）：包含文档和源码（适合深入学习）。
• 源码包（Source）：需自行编译。

---

安装 Gradle

前置条件

• 已安装 JDK 8 或更高版本（通过 java -version 验证）。

安装步骤（以 Linux/macOS 为例）

1. 解压安装包

# 解压到 /opt/gradle（需 sudo 权限）
sudo unzip -d /opt/gradle gradle-8.5-bin.zip

2. 配置环境变量

编辑 ~/.bashrc 或 ~/.zshrc，添加：

export GRADLE_HOME=/opt/gradle/gradle-8.5
export PATH=$GRADLE_HOME/bin:$PATH

生效配置：

source ~/.bashrc

3. 验证安装

gradle -v  # 输出版本信息即成功

Windows 安装

1. 解压 ZIP 包到 C:\gradle 等目录。
2. 配置系统环境变量：
   • 新增 GRADLE_HOME=C:\gradle\gradle-8.5
   • 在 Path 中添加 %GRADLE_HOME%\bin
3. 在 CMD 中运行 gradle -v 验证。

---

升级 Gradle

1. 下载新版本并解压到新目录。
2. 更新 GRADLE_HOME 环境变量指向新路径。
3. 验证版本：

   gradle -v
   

---

注意事项

1. 权限问题：Linux/macOS 中确保对安装目录有读写权限。
2. 多版本管理：
   • 使用工具如 SDKMAN!（推荐）：

     sdk install gradle 8.5
     sdk use gradle 8.5
     

3. 代理配置：若下载依赖慢，在 ~/.gradle/gradle.properties 中添加：

   systemProp.http.proxyHost=proxy.example.com
   systemProp.http.proxyPort=8080
   

---

示例：快速验证安装

创建 build.gradle 文件：

task hello {
    doLast {
        println 'Gradle installed successfully!'
    }
}

运行任务：

gradle hello

---

配置环境变量

什么是环境变量

环境变量是操作系统或应用程序运行时使用的动态值，用于存储系统路径、配置信息等。在 Gradle 中，环境变量常用于配置 Java 路径、代理设置或自定义构建参数。

常见使用场景

1. 设置 JAVA_HOME：指定 JDK 安装路径
2. 配置代理：设置 HTTP/HTTPS 代理
3. 自定义构建参数：传递敏感信息（如 API 密钥）

配置方法（Windows/Linux/macOS）

Windows 系统

1. 打开系统属性 → 高级 → 环境变量
2. 在"用户变量"或"系统变量"中添加/编辑变量：
   • 变量名：JAVA_HOME
   • 变量值：C:\Program Files\Java\jdk-17

Linux/macOS 系统

# 临时设置（仅当前会话有效）
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk

# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk' >> ~/.bashrc
source ~/.bashrc

Gradle 中使用环境变量

// build.gradle 中读取环境变量
task printEnv {
    doLast {
        println "JAVA_HOME: ${System.getenv('JAVA_HOME')}"
        println "自定义变量: ${System.getenv('MY_VAR')}"
    }
}

注意事项

1. 修改后需要重启终端/IDE才能生效
2. 路径中避免使用中文和特殊字符
3. Windows 路径使用反斜杠需要转义（C:\\Path\\To\\JDK）
4. 敏感信息建议使用 GRADLE_USER_HOME/gradle.properties 存储

验证配置

# 检查环境变量是否生效
gradle printEnv

# 或直接查看
echo $JAVA_HOME  # Linux/macOS
echo %JAVA_HOME% # Windows

---

验证 Gradle 安装是否成功

1. 通过命令行验证

安装完成后，可以通过以下命令验证 Gradle 是否正确安装：

gradle -v

或

gradle --version

2. 预期输出

如果安装成功，命令行会显示类似以下信息：

------------------------------------------------------------
Gradle 8.5
------------------------------------------------------------

Build time:   2023-11-28 15:24:16 UTC
Revision:     d90a1c9b7b554f6f5d0f3002aed5a1d7d317d4d3

Kotlin:       1.9.20
Groovy:       3.0.17
Ant:          Apache Ant(TM) version 1.10.13 compiled on January 4 2023
JVM:          17.0.9 (Oracle Corporation 17.0.9+9-LTS-211)
OS:           Windows 10 10.0 amd64

3. 检查内容

输出信息中包含以下关键内容：

• Gradle 版本号
• 构建时间
• 使用的 Kotlin、Groovy 和 Ant 版本
• JVM 版本信息
• 操作系统信息

4. 常见问题

如果命令执行失败，可能的原因包括：

• Gradle 未正确安装
• 系统 PATH 环境变量未配置 Gradle 的 bin 目录
• 多个 Gradle 版本冲突

5. 验证 Gradle 运行

可以进一步创建一个简单的构建脚本验证 Gradle 是否能正常运行：

mkdir test-project
cd test-project
gradle init --type basic
gradle build

如果这些命令能成功执行，说明 Gradle 安装完全正确。

---

Gradle Wrapper 概述

Gradle Wrapper 是一个用于自动化 Gradle 版本管理的工具，它允许项目在不预先安装 Gradle 的情况下，通过一个脚本自动下载并使用指定的 Gradle 版本进行构建。它的核心目标是确保构建环境的一致性，避免因开发人员本地 Gradle 版本不同而导致构建失败。

核心文件

Gradle Wrapper 由以下几个文件组成：

• gradlew（Unix/Linux/macOS 脚本）
• gradlew.bat（Windows 批处理脚本）
• gradle/wrapper/gradle-wrapper.properties（配置文件）
• gradle/wrapper/gradle-wrapper.jar（Wrapper 核心逻辑实现）

---

为什么使用 Gradle Wrapper？

1. 版本一致性

• 确保所有开发人员和 CI/CD 环境使用相同的 Gradle 版本，避免因版本差异导致的构建问题。
• 项目提交到版本控制系统（如 Git）时，Wrapper 文件会一并纳入管理。

2. 零配置入门

• 新成员克隆项目后，无需手动安装 Gradle，直接运行 gradlew 即可开始构建。
• 尤其适合团队协作或开源项目。

3. 灵活升级

• 通过修改 gradle-wrapper.properties 即可升级或降级 Gradle 版本，无需全局安装。

---

如何使用 Gradle Wrapper？

生成 Wrapper

如果项目尚未包含 Wrapper，可以通过以下命令生成（需已安装 Gradle）：

gradle wrapper --gradle-version 8.5

这会创建 Wrapper 文件并指定 Gradle 版本为 8.5。

常用命令

• 构建项目：

  ./gradlew build      # Unix/Linux/macOS
  gradlew.bat build    # Windows
  

• 清理构建：

  ./gradlew clean
  

• 查看可用任务：

  ./gradlew tasks
  

---

配置 Gradle Wrapper

修改版本

编辑 gradle-wrapper.properties 文件：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip

• distributionUrl：指定 Gradle 发行版的下载地址。
  • -bin.zip：仅包含运行时（推荐大多数场景）。
  • -all.zip：包含源码和文档（适合需要调试的场景）。

自定义下载路径

可以通过环境变量 GRADLE_USER_HOME 修改 Wrapper 下载的 Gradle 存储路径（默认在用户目录的 .gradle/wrapper/dists 下）。

---

注意事项

1. 首次运行较慢

• Wrapper 首次运行时会下载指定版本的 Gradle，后续构建会直接使用缓存。

2. 网络依赖

• 需确保构建环境能访问 services.gradle.org（或配置镜像仓库）。

3. 权限问题

• 在 Unix 系统下，首次运行前需为 gradlew 添加可执行权限：

  chmod +x gradlew
  

4. 版本兼容性

• 如果项目使用了新版本的 Gradle 特性，但 Wrapper 配置了旧版本，会导致构建失败。需同步升级 Wrapper 配置。

---

示例：从零创建 Wrapper

1. 初始化一个 Gradle 项目（假设使用 Groovy DSL）：

   mkdir my-project && cd my-project
   gradle init --type java-application
   

2. 生成 Wrapper：

   gradle wrapper --gradle-version 8.5 --distribution-type bin
   

3. 通过 Wrapper 构建：

   ./gradlew build
   

此时项目目录会包含 Wrapper 文件，其他成员克隆后可直接运行 ./gradlew build。

---

三、Gradle 基础概念

项目（Project）与任务（Task）

概念定义

在 Gradle 中，项目（Project） 和 任务（Task） 是两个核心概念，构成了构建逻辑的基本单元。

1. 项目（Project）

   • 代表一个独立的构建单元，通常对应一个软件模块或组件。
   • 每个 Gradle 构建由一个或多个项目组成（例如多模块项目）。
   • 项目通过 build.gradle 或 build.gradle.kts 文件定义其属性和行为。

2. 任务（Task）

   • 是项目中的最小执行单元，代表一个具体的构建操作（如编译、打包、测试等）。
   • 任务由动作（Action）和依赖关系组成，形成一个有向无环图（DAG）。
   • 例如：compileJava、test、jar 都是常见的内置任务。

关系与层级

• 一个项目包含多个任务。
• 任务之间可以定义依赖关系（如任务 B 必须在任务 A 完成后执行）。
• 多项目构建时，项目之间也可以定义依赖关系。

---

使用场景

1. 单项目构建
   直接通过任务执行构建操作，例如：

   gradle build  # 执行默认任务链（编译、测试、打包）
   gradle test   # 仅运行测试任务
   

2. 多项目构建
   通过 settings.gradle 定义子项目，并在根项目中管理任务依赖：

   // settings.gradle
   include 'app', 'library'  # 包含两个子项目
   

3. 自定义任务
   在 build.gradle 中定义新任务：

   task hello {
       doLast {
           println "Hello, Gradle!"
       }
   }
   

---

常见误区与注意事项

1. 任务配置与执行顺序

   • 任务配置阶段（Configuration Phase）的代码会在构建开始时立即执行，而动作（doLast 或 doFirst）仅在执行阶段（Execution Phase）运行。
   • 错误示例：

     task wrongExample {
         println "This runs during configuration!"  // 错误：配置阶段即执行
         doLast {
             println "This runs during execution."
         }
     }
     

2. 任务依赖循环
   避免任务 A 依赖任务 B，同时任务 B 又依赖任务 A，否则会导致构建失败。

3. 任务输入/输出声明
   为任务显式声明输入和输出以支持增量构建：

   task processFiles {
       inputs.files fileTree("src/data")
       outputs.dir "build/processed"
       doLast {
           // 处理文件逻辑
       }
   }
   

---

示例代码

1. 多任务依赖

   task compile {
       doLast {
           println "Compiling source code..."
       }
   }
   
   task test(dependsOn: compile) {
       doLast {
           println "Running tests..."
       }
   }
   
   task deploy(dependsOn: test) {
       doLast {
           println "Deploying application..."
       }
   }
   

   执行 gradle deploy 会按顺序触发 compile → test → deploy。

2. 动态任务创建

   3.times { index ->
       task "task$index" {
           doLast {
               println "I'm task $index"
           }
       }
   }
   

   生成 task0、task1、task2 三个任务。

---

构建脚本（build.gradle）

概念定义

build.gradle 是 Gradle 构建工具的核心配置文件，采用 Groovy 或 Kotlin DSL（领域特定语言）编写。它定义了项目的构建逻辑，包括依赖管理、任务定义、插件应用等。Gradle 通过解析该脚本自动执行构建流程。

文件位置与类型

1. 项目级构建脚本：位于项目根目录，配置全局设置（如所有子模块共享的插件或仓库）。

   // 示例：根项目的 build.gradle
   buildscript {
       repositories {
           google()
           mavenCentral()
       }
       dependencies {
           classpath "com.android.tools.build:gradle:7.0.0"
       }
   }
   

2. 模块级构建脚本：位于子模块目录（如 app/），配置模块特定的构建规则。

   // 示例：Android 模块的 build.gradle
   plugins {
       id 'com.android.application'
   }
   android {
       compileSdkVersion 31
   }
   

核心组成部分

1. 插件声明：通过 plugins 块引入功能（如 Java、Android 或 Spring Boot 插件）。

   plugins {
       id 'java' // Java 项目基础插件
       id 'org.springframework.boot' version '2.5.0' // Spring Boot 插件
   }
   

2. 依赖管理：在 dependencies 块中声明库依赖，支持多种作用域（如 implementation、testImplementation）。

   dependencies {
       implementation 'org.apache.commons:commons-lang3:3.12.0'
       testImplementation 'junit:junit:4.13.2'
   }
   

3. 任务定义：自定义任务或修改现有任务的行为。

   task hello {
       doLast {
           println 'Hello, Gradle!'
       }
   }
   

动态特性

1. Groovy/Kotlin 能力：可直接调用语言特性（如循环、条件判断）。

   android.buildTypes.each { type ->
       type.buildConfigField 'String', 'API_KEY', '"123456"'
   }
   

2. 扩展属性：通过 ext 块定义全局变量供多脚本共享。

   // 根项目 build.gradle
   ext {
       kotlinVersion = '1.6.0'
   }
   // 子模块引用
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlinVersion"
   

常见误区

1. 依赖作用域混淆：

   • implementation：当前模块私有依赖。
   • api：暴露依赖给其他模块。
   • 错误使用可能导致编译冲突或构建变慢。

2. 脚本执行顺序：

   • 根项目的 buildscript 块优先执行。
   • 子模块脚本按依赖顺序执行，而非文件位置。

3. Groovy 语法陷阱：

   • 字符串引号：单引号（静态字符串） vs 双引号（支持插值）。

     def version = '1.0'
     println "Version: $version" // 正确插值
     println 'Version: $version' // 输出字面量
     

调试技巧

1. 查看任务列表：运行 gradle tasks --all。
2. 日志输出：使用 logger 对象或 println。

   tasks.register('debugTask') {
       doLast {
           logger.quiet('自定义日志级别输出')
       }
   }
   

进阶用法

1. 脚本模块化：通过 apply from: 'path/to/script.gradle' 复用配置。
2. 自定义插件：将复杂逻辑封装为独立插件。
3. 增量构建：通过 inputs/outputs 标记任务输入输出以优化性能。

---

Gradle 构建生命周期

构建阶段概述

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

1. 初始化阶段：确定哪些项目参与构建，并为每个项目创建 Project 实例
2. 配置阶段：执行构建脚本（build.gradle），配置任务对象和依赖关系
3. 执行阶段：根据任务依赖关系图执行指定的任务

初始化阶段

• 解析 settings.gradle 文件
• 确定单项目或多项目结构
• 创建项目层级结构
• 典型场景：多项目构建时确定子项目包含关系

配置阶段

• 执行所有 build.gradle 脚本
• 构建任务对象的有向无环图（DAG）
• 注意：此阶段会执行所有任务配置代码，无论任务是否最终被执行
• 常见误区：在配置阶段执行耗时操作（应使用 doFirst/doLast）

执行阶段

• Gradle 根据任务依赖关系确定执行顺序
• 只执行被请求的任务及其依赖任务
• 每个任务包含多个动作（Action），按 doFirst 和 doLast 顺序执行

生命周期监听

可以通过 API 监听构建生命周期事件：

// 项目评估前
gradle.beforeProject { project ->
    println "准备配置项目: $project"
}

// 任务图就绪后
gradle.taskGraph.whenReady { graph ->
    println "任务图已就绪，将执行${graph.allTasks.size()}个任务"
}

// 构建完成后
gradle.buildFinished { result ->
    println "构建${result.failure ? '失败' : '成功'}"
}

任务执行顺序控制

1. 依赖声明：

task A {
    dependsOn 'B'
    doLast { println "执行A" }
}
task B {
    doLast { println "执行B" }
}

2. 顺序规则：

task C {
    mustRunAfter 'D'
    doLast { println "执行C" }
}
task D {
    doLast { println "执行D" }
}

性能优化建议

• 避免在配置阶段执行实际工作
• 使用 configure-on-demand 模式（只配置相关项目）
• 使用 --profile 参数生成构建性能报告
• 对耗时任务配置增量构建（@Input/@Output 注解）

常见问题

1. 配置阶段耗时过长：将逻辑移到任务动作中
2. 任务执行顺序不符合预期：检查 dependsOn 和 mustRunAfter
3. 多项目构建配置泄漏：使用 subprojects 或 allprojects 时要谨慎

---

依赖管理基础

什么是依赖管理

依赖管理是构建工具的核心功能之一，用于声明、解析和传递项目所需的第三方库或模块。在Gradle中，依赖管理通过声明依赖关系来自动下载所需的JAR文件，并处理版本冲突等问题。

依赖配置（Configurations）

Gradle使用**配置（Configurations）**来定义依赖的作用范围，常见配置包括：

• implementation：编译和运行时依赖（推荐默认使用）
• compileOnly：仅编译时依赖（如注解处理器）
• runtimeOnly：仅运行时依赖（如数据库驱动）
• testImplementation：测试代码的依赖

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web:2.7.0'
    testImplementation 'junit:junit:4.13.2'
}

依赖类型

1. 模块依赖：从仓库获取的库（最常见）

   implementation group: 'com.google.guava', name: 'guava', version: '31.1-jre'
   

2. 项目依赖：依赖本地其他模块

   implementation project(':core-module')
   

3. 文件依赖：直接引入本地JAR

   implementation files('libs/local-lib.jar')
   

依赖仓库（Repositories）

Gradle从预定义的仓库下载依赖，默认使用Maven Central：

repositories {
    mavenCentral()
    // 或自定义仓库
    maven { url 'https://maven.aliyun.com/repository/public' }
}

依赖传递与冲突解决

• 传递性依赖：A依赖B，B依赖C → A自动依赖C
• 版本冲突处理策略：
  • failOnVersionConflict()：默认立即失败
  • 强制指定版本：

    configurations.all {
        resolutionStrategy.force 'com.google.guava:guava:31.1-jre'
    }
    

常见问题与建议

1. 避免使用compile：已被implementation取代，后者能减少不必要的编译类路径泄露
2. 锁定动态版本：避免使用1.0.+等动态版本，推荐明确版本号
3. 查看依赖树：通过命令排查冲突

   gradle dependencies
   

示例：完整的build.gradle

plugins {
    id 'java'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.apache.commons:commons-lang3:3.12.0'
    testImplementation 'org.junit.jupiter:junit-jupiter:5.8.1'
}

---

四、构建脚本编写

Groovy 与 Kotlin DSL

概念定义

1. Groovy
   Groovy 是一种基于 JVM 的动态类型编程语言，语法与 Java 兼容但更简洁。在 Gradle 中，Groovy 是传统的 DSL（领域特定语言）实现方式，通过闭包和动态特性实现灵活的构建脚本编写。

2. Kotlin DSL
   Kotlin DSL 是 Gradle 官方支持的另一种脚本编写方式，基于静态类型的 Kotlin 语言。它提供类型安全、更好的 IDE 支持（如代码补全和重构），并且语法更接近现代编程风格。

使用场景

1. Groovy DSL 适用场景

   • 需要快速原型开发或动态配置。
   • 对 Java 开发者友好，学习曲线平缓。
   • 传统 Gradle 项目或已有大量 Groovy 脚本的迁移成本较高时。

2. Kotlin DSL 适用场景

   • 需要类型安全和编译时检查。
   • 项目规模较大，需更好的 IDE 支持（如 Android Studio 或 IntelliJ IDEA）。
   • 团队已熟悉 Kotlin 或希望统一技术栈。

语法对比示例

1. 依赖声明

   • Groovy DSL：

     dependencies {
         implementation 'com.android.support:appcompat-v7:28.0.0'
         testImplementation 'junit:junit:4.12'
     }
     

   • Kotlin DSL：

     dependencies {
         implementation("com.android.support:appcompat-v7:28.0.0")
         testImplementation("junit:junit:4.12")
     }
     

2. 任务定义

   • Groovy DSL：

     task hello {
         doLast {
             println 'Hello, Gradle!'
         }
     }
     

   • Kotlin DSL：

     tasks.register("hello") {
         doLast {
             println("Hello, Gradle!")
         }
     }
     

常见误区与注意事项

1. Groovy DSL 的陷阱

   • 动态类型：拼写错误或方法名错误可能在运行时才暴露。
   • 闭包语法：it 默认参数和括号省略可能导致初学者困惑。

2. Kotlin DSL 的挑战

   • 编译时间：Kotlin 脚本需要编译，可能略微增加构建配置时间。
   • 兼容性：某些旧插件可能未完全适配 Kotlin DSL。

3. 通用建议

   • 新项目优先选择 Kotlin DSL，尤其是团队熟悉 Kotlin 时。
   • 混合项目可逐步迁移，通过 build.gradle.kts 和 build.gradle 共存实现过渡。

性能与工具支持

1. IDE 支持

   • Kotlin DSL 在 IntelliJ 系列 IDE 中支持更完善（如代码导航、错误提示）。
   • Groovy DSL 的 IDE 补全较弱，依赖插件文档。

2. 构建速度

   • Kotlin DSL 因静态类型检查在大型项目中可能更高效。
   • Groovy DSL 的动态解析在小项目中启动更快。

---

任务定义与配置

任务定义

在 Gradle 中，任务（Task） 是最基本的执行单元，代表构建过程中的一个独立操作。每个任务可以包含一系列动作（Action），用于完成特定的构建工作，例如编译代码、运行测试或打包项目。

任务可以通过以下方式定义：

1. 使用任务名称和闭包

   task hello {
       doLast {
           println 'Hello, Gradle!'
       }
   }
   

2. 通过 TaskContainer 的 create 方法

   tasks.create('hello') {
       doLast {
           println 'Hello, Gradle!'
       }
   }
   

3. 使用任务类型（预定义或自定义）

   task copyFiles(type: Copy) {
       from 'src/main/resources'
       into 'build/resources'
   }
   

任务配置

任务配置用于定义任务的属性、依赖关系和执行逻辑。常见的配置方式包括：

1. 动作（Action）

   • doFirst：在任务执行开始时运行。
   • doLast（或 <<）：在任务执行结束时运行。

   task hello {
       doFirst {
           println 'Starting hello task'
       }
       doLast {
           println 'Hello, Gradle!'
       }
   }
   

2. 依赖关系
   通过 dependsOn 指定任务依赖的其他任务：

   task compile {
       doLast {
           println 'Compiling source code'
       }
   }
   task test(dependsOn: compile) {
       doLast {
           println 'Running tests'
       }
   }
   

3. 任务属性
   可以配置任务的描述、分组等属性：

   task hello {
       group = 'Custom'
       description = 'Prints a greeting message'
       doLast {
           println 'Hello, Gradle!'
       }
   }
   

4. 动态任务
   可以通过编程方式动态创建任务：

   3.times { i ->
       task "task$i" {
           doLast {
               println "Executing task $i"
           }
       }
   }
   

常见误区与注意事项

1. 任务配置与执行顺序

   • 任务配置阶段（Configuration Phase）和执行阶段（Execution Phase）是分开的。
   • 避免在配置阶段执行耗时操作，应将其放在 doFirst 或 doLast 中。

2. 任务依赖循环

   • 避免任务之间的循环依赖，否则会导致构建失败。
   • 例如，taskA 依赖 taskB，而 taskB 又依赖 taskA。

3. 任务名称冲突

   • 确保任务名称唯一，否则会覆盖已有任务。

4. 惰性配置

   • 对于复杂构建，建议使用 tasks.register（惰性注册）而非 tasks.create（立即创建）：

   tasks.register('hello') {
       doLast {
           println 'Hello, Gradle!'
       }
   }
   

示例代码

以下是一个完整的任务定义与配置示例：

task compile {
    group = 'Build'
    description = 'Compiles the source code'
    doLast {
        println 'Compiling source code...'
    }
}

task test(dependsOn: compile) {
    group = 'Verification'
    description = 'Runs the unit tests'
    doLast {
        println 'Running tests...'
    }
}

task build(dependsOn: test) {
    group = 'Build'
    description = 'Builds the project'
    doLast {
        println 'Building the project...'
    }
}

运行 gradle build 时，任务将按以下顺序执行：

1. compile
2. test
3. build

---

依赖声明

概念定义

依赖声明是 Gradle 构建脚本中用于指定项目所需外部库或模块的部分。通过声明依赖，Gradle 可以自动下载和管理这些外部资源，确保项目能够正确编译和运行。

语法格式

在 Gradle 中，依赖通常在 dependencies 块中声明，格式如下：

dependencies {
    implementation 'group:name:version'
    testImplementation 'group:name:version'
}

常用配置类型

1. implementation：用于主源代码编译和运行时依赖
2. compileOnly：仅在编译时需要，运行时不需要
3. runtimeOnly：仅在运行时需要，编译时不需要
4. testImplementation：测试代码的依赖
5. annotationProcessor：注解处理器依赖

示例

dependencies {
    // Spring Boot Web 依赖
    implementation 'org.springframework.boot:spring-boot-starter-web:2.7.0'
    
    // Lombok 注解处理器
    compileOnly 'org.projectlombok:lombok:1.18.24'
    annotationProcessor 'org.projectlombok:lombok:1.18.24'
    
    // JUnit 测试框架
    testImplementation 'junit:junit:4.13.2'
}

注意事项

1. 版本号应该明确指定，避免使用动态版本（如 1.+）
2. 不同配置类型的依赖有不同的传递性
3. 依赖冲突时，Gradle 默认会使用最高版本

仓库配置

概念定义

仓库配置指定了 Gradle 从哪里获取依赖项。Gradle 支持多种类型的仓库，包括 Maven 中央仓库、JCenter、本地仓库以及自定义仓库。

常见仓库类型

1. Maven Central：最常用的公共仓库
2. Google Maven：Google 提供的 Android 相关库
3. JCenter（已废弃）：曾经是另一个主要的公共仓库
4. 本地 Maven 仓库：~/.m2/repository
5. 自定义仓库：公司内部搭建的私有仓库

配置语法

仓库通常在 repositories 块中配置：

repositories {
    mavenCentral()
    google()
    mavenLocal()
    maven {
        url 'https://custom.repo.com/repository'
    }
}

示例配置

repositories {
    // 阿里云镜像仓库（推荐国内使用）
    maven { url 'https://maven.aliyun.com/repository/public' }
    maven { url 'https://maven.aliyun.com/repository/google' }
    
    // 公司私有仓库
    maven {
        url 'https://nexus.company.com/repository/maven-releases'
        credentials {
            username 'user'
            password 'password'
        }
    }
    
    // 本地仓库
    mavenLocal()
}

最佳实践

1. 国内开发者建议使用阿里云等镜像仓库加速下载
2. 私有仓库应该配置认证信息
3. 仓库顺序会影响依赖解析效率（常用仓库应放前面）
4. 避免同时配置多个可能包含相同依赖的仓库

常见问题

1. 依赖下载失败时，检查仓库配置和网络连接
2. 私有仓库认证失败时，检查凭据是否正确
3. 不同仓库中的相同依赖版本不一致可能导致冲突

---

插件应用

概念定义

Gradle 插件是一种用于扩展 Gradle 构建系统功能的模块化组件。插件可以封装一系列任务（Tasks）、依赖项（Dependencies）、配置（Configurations）和扩展属性（Extensions），以便在多个项目中复用。通过应用插件，开发者可以快速引入预定义的功能，而无需手动编写大量构建逻辑。

使用场景

1. 构建工具插件：如 java、application 插件，用于编译 Java 代码或打包可执行应用。
2. 测试插件：如 junit 插件，用于运行单元测试。
3. 代码质量检查插件：如 checkstyle、pmd 插件，用于静态代码分析。
4. 部署插件：如 maven-publish 插件，用于将构建产物发布到 Maven 仓库。
5. 自定义插件：开发者可以编写自己的插件以满足特定需求。

常见误区或注意事项

1. 插件冲突：多个插件可能定义相同的任务名称，导致构建失败或行为异常。
2. 插件版本兼容性：某些插件需要特定版本的 Gradle 或其他插件支持。
3. 过度依赖插件：不必要的插件会增加构建时间和复杂度。
4. 插件作用域：插件可以应用于整个项目（plugins 块）或特定子项目（subprojects 块）。

示例代码

应用核心插件（如 java 插件）

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

应用社区插件（如 spring-boot 插件）

plugins {
    id 'org.springframework.boot' version '3.1.0' // 指定插件版本
}

在子项目中应用插件

subprojects {
    apply plugin: 'java' // 为所有子项目应用 Java 插件
}

自定义插件配置

plugins {
    id 'java'
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(11) // 配置 Java 版本
    }
}

插件类型

1. 二进制插件：通过 id 和版本号引用（如 id 'java'）。
2. 脚本插件：通过 apply from: 'path/to/script.gradle' 引入外部脚本。
3. 约定插件：在 buildSrc 目录中定义的自定义插件。

---

五、常用命令

常见构建命令（build、clean、test等）

Gradle 提供了一系列内置的构建命令，用于执行常见的构建任务。这些命令可以通过命令行或集成开发环境（IDE）来调用。以下是几个最常用的构建命令及其详细说明：

build

build 是 Gradle 中最常用的命令之一，用于执行项目的完整构建流程。它会依次执行编译、测试、打包等任务。

使用场景：

• 当需要构建整个项目并生成最终的可交付物（如 JAR、WAR 文件）时。
• 在发布或部署项目之前，确保所有代码通过编译和测试。

执行方式：

gradle build

注意事项：

1. build 是一个聚合任务，它会依赖其他任务（如 compileJava、test、jar 等）。
2. 如果项目中存在测试失败的情况，build 任务会终止并报错。

clean

clean 命令用于清理项目的构建输出目录（通常是 build 目录），删除所有生成的构建文件。

使用场景：

• 当需要从头开始重新构建项目时。
• 当构建过程中出现不可预料的错误，怀疑是缓存或旧构建文件导致的问题时。

执行方式：

gradle clean

注意事项：

1. 执行 clean 后，所有中间文件和最终构建产物都会被删除，下次构建需要重新生成。
2. 可以结合 build 使用，如 gradle clean build，表示先清理再重新构建。

test

test 命令用于执行项目中的单元测试。

使用场景：

• 在开发过程中快速验证代码的正确性。
• 在持续集成（CI）流程中自动运行测试。

执行方式：

gradle test

注意事项：

1. 测试结果默认会生成在 build/reports/tests 目录下，包括 HTML 和 XML 格式的报告。
2. 如果任何测试失败，Gradle 会标记任务为失败，并停止后续的构建步骤（除非配置了 --continue 参数）。

run

run 命令用于运行应用程序的主类。

使用场景：

• 快速启动和调试应用程序。
• 在开发环境中验证功能。

执行方式：

gradle run

注意事项：

1. run 任务需要配置主类（mainClassName），通常在 application 插件中指定。
2. 仅适用于有主类的应用程序（如 Java 的 public static void main 方法）。

assemble

assemble 命令用于编译和打包项目，但不运行测试。

使用场景：

• 当只需要生成构建产物（如 JAR 文件）而不需要运行测试时。
• 在快速迭代开发中，节省时间。

执行方式：

gradle assemble

注意事项：

1. assemble 是 build 的子集，它只包含编译和打包任务，不包含测试。
2. 生成的构建产物位于 build/libs 目录下。

check

check 命令用于运行所有的验证任务，通常包括测试和代码质量检查（如静态分析）。

使用场景：

• 在代码提交前，确保代码符合质量要求。
• 在 CI 流程中执行全面的代码验证。

执行方式：

gradle check

注意事项：

1. check 依赖于 test 和其他代码质量插件（如 checkstyle、pmd）的任务。
2. 如果配置了代码质量检查工具，失败的任务会导致 check 失败。

其他常用命令

1. dependencies：显示项目的依赖树。

   gradle dependencies
   

2. tasks：列出项目中所有可用的任务。

   gradle tasks
   

3. jar：仅打包生成 JAR 文件。

   gradle jar
   

示例代码

以下是一个简单的 build.gradle 文件，展示了如何配置 application 插件和主类：

plugins {
    id 'application'
}

application {
    mainClassName = 'com.example.Main'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.apache.commons:commons-lang3:3.12.0'
    testImplementation 'junit:junit:4.13.2'
}

通过这些命令，可以高效地管理和构建 Gradle 项目。

---

任务查看与执行

任务查看

在 Gradle 中，任务（Task）是构建过程中的基本执行单元。通过查看项目中的所有任务，可以更好地理解构建流程。以下是查看任务的常用方式：

1. 查看所有任务
   在项目根目录下执行以下命令：

   gradle tasks
   

   这会列出所有可用的任务，并按类别分组（如 Build tasks、Documentation tasks 等）。

2. 查看特定任务组的任务
   使用 --group 参数可以过滤特定组的任务：

   gradle tasks --group=build
   

3. 查看任务的详细信息
   通过 --all 参数可以显示任务的详细描述和依赖关系：

   gradle tasks --all
   

任务执行

1. 执行单个任务
   直接指定任务名称即可执行：

   gradle build
   

2. 执行多个任务
   可以一次性执行多个任务，按顺序排列：

   gradle clean build
   

3. 任务名称缩写
   Gradle 支持任务名称的驼峰式缩写。例如：

   gradle b
   

   如果只有一个任务以 b 开头（如 build），则会执行该任务。

4. 排除任务
   使用 -x 参数可以排除某个任务：

   gradle build -x test
   

   这会执行 build 任务，但跳过 test 任务。

5. 强制执行任务
   使用 --rerun-tasks 可以强制重新执行任务，即使任务已经是最新状态：

   gradle build --rerun-tasks
   

常见误区与注意事项

1. 任务名称区分大小写
   Gradle 任务名称是区分大小写的。例如 build 和 Build 是两个不同的任务。

2. 任务依赖关系
   某些任务可能依赖于其他任务。执行时，Gradle 会自动解析依赖关系并按顺序执行。例如：

   gradle assemble
   

   可能会先执行 compileJava 和 processResources 任务。

3. 增量构建
   Gradle 默认支持增量构建，如果任务的输入和输出未发生变化，则不会重新执行。可以通过 --rerun-tasks 强制重新运行。

4. 并行执行
   使用 --parallel 可以并行执行独立任务以提升构建速度：

   gradle build --parallel
   

示例代码

以下是一个简单的 build.gradle 文件，定义了几个自定义任务：

task hello {
    doLast {
        println 'Hello, Gradle!'
    }
}

task compile(type: Exec) {
    commandLine 'javac', 'src/main/java/App.java'
}

task run(type: Exec, dependsOn: 'compile') {
    commandLine 'java', '-cp', 'src/main/java', 'App'
}

执行示例：

gradle hello       # 执行 hello 任务
gradle run         # 执行 run 任务（会自动先执行 compile）
gradle tasks --all # 查看所有任务及其依赖关系

通过以上方法，可以高效地查看和执行 Gradle 任务，从而更好地管理构建流程。

---

命令行参数

概念定义

命令行参数（Command Line Arguments）是在执行 Gradle 构建任务时，通过命令行传递给 Gradle 的额外配置选项或参数。这些参数可以控制构建的行为、配置项目属性或传递自定义值。

使用场景

1. 控制构建行为：如指定构建环境（--debug）、跳过测试（-x test）等。
2. 传递项目属性：通过 -P 传递自定义属性（如 -Pversion=1.0）。
3. 配置系统属性：通过 -D 设置 JVM 系统属性（如 -Dorg.gradle.debug=true）。
4. 指定任务执行：如运行特定任务（gradle build）或任务组合（gradle clean build）。

常见参数类型

1. 标准参数

• --help 或 -h：显示帮助信息。
• --version：显示 Gradle 版本。
• --quiet 或 -q：减少日志输出。
• --info：显示详细日志。
• --debug 或 -d：启用调试模式。

2. 项目属性参数

• -P<key>=<value>：传递项目属性。

  gradle build -Penv=prod -Pversion=2.0
  

  在 build.gradle 中可通过 project.properties['env'] 访问。

3. 系统属性参数

• -D<key>=<value>：设置 JVM 系统属性。

  gradle test -Dorg.gradle.parallel=true
  

  在代码中可通过 System.getProperty("org.gradle.parallel") 获取。

4. 任务控制参数

• -x <task>：排除指定任务。

  gradle build -x test  # 跳过测试任务
  

• --rerun-tasks：强制重新运行所有任务（忽略缓存）。

示例代码

在 build.gradle 中使用命令行参数

task printArgs {
    doLast {
        // 访问项目属性
        println "Environment: ${project.properties.get('env', 'dev')}"
        
        // 访问系统属性
        println "Parallel mode: ${System.getProperty('org.gradle.parallel')}"
    }
}

执行命令：

gradle printArgs -Penv=prod -Dorg.gradle.parallel=true

常见误区与注意事项

1. 参数顺序敏感：部分参数（如 -P 和 -D）需在任务名前指定。

   gradle -Pkey=value taskName  # 正确
   gradle taskName -Pkey=value  # 可能无效
   

2. 布尔值传递：Gradle 中 -Pflag=true 会被解析为字符串，需显式转换：

   def flag = Boolean.parseBoolean(project.properties.get('flag', 'false'))
   

3. 默认值处理：建议为动态属性设置默认值，避免未传递参数时抛出异常。
4. 缓存影响：部分参数（如 -P）可能影响任务缓存键，导致不必要的重建。

---

构建缓存（Build Cache）

概念定义

构建缓存是 Gradle 的核心优化机制，用于存储和复用先前构建任务的输出结果。当相同的输入（如源代码、依赖项）再次出现时，Gradle 可以直接从缓存中获取结果，避免重复执行任务。

工作原理

1. 缓存键生成：Gradle 会为每个任务生成唯一的缓存键（基于输入文件内容、任务类型、依赖关系等）。
2. 本地/远程缓存：
   • 本地缓存：默认存储在项目目录下的 .gradle/build-cache 中。
   • 远程缓存：可配置为团队共享（如 HTTP 服务器或 S3 存储桶）。
3. 命中检查：执行任务前，Gradle 会检查缓存是否存在匹配的键。

使用场景

• 多模块项目中重复构建相同模块
• CI/CD 环境中多个构建节点共享缓存
• 开发者在 clean 后重新构建时加速构建

配置示例（settings.gradle）

buildCache {
    local {
        directory = new File(rootDir, 'build-cache')
        removeUnusedEntriesAfterDays = 30
    }
    remote(HttpBuildCache) {
        url = 'https://example.com/cache/'
        credentials {
            username = 'user'
            password = 'secret'
        }
    }
}

注意事项

1. 缓存敏感任务需要显式声明输入/输出（如使用 @Input 注解）
2. 非确定性任务（如含时间戳）会导致缓存失效
3. 远程缓存需考虑安全性（建议 HTTPS + 认证）

---

增量构建（Incremental Build）

概念定义

增量构建指 Gradle 仅重新执行受更改影响的任务及其下游任务，而非完整重建。通过对比输入/输出的变化决定任务是否需要执行。

工作原理

1. 任务输入/输出快照：Gradle 记录任务的输入文件内容哈希和输出文件状态。
2. 变化检测：
   • 输入变化：比较当前输入与上次构建的快照
   • 输出缺失：检查预期输出文件是否存在
3. 任务跳过：当输入未变化且输出存在时标记为 UP-TO-DATE

使用场景

• 开发过程中频繁修改少量文件
• 大型项目部分模块未变更时
• 运行测试时仅执行受影响的测试套件

示例（自定义任务实现增量）

task processTemplates(type: Copy) {
    inputs.property("version", project.version)
    inputs.dir("src/templates")
    outputs.dir("$buildDir/generated")
    
    from("src/templates")
    into("$buildDir/generated")
    expand(version: project.version)
}

常见问题

1. 误判更新：
   • 未声明所有输入（如系统属性）
   • 输出文件被外部修改
2. 任务非幂等：任务执行结果受外部状态影响
3. 调试技巧：

   gradle build --info  # 查看任务跳过原因
   gradle clean        # 强制全量重建
   

---

缓存与增量构建的关系

协同工作流程

1. 增量构建首先检查任务是否需要执行
2. 需要执行时，优先查询构建缓存
3. 缓存命中则直接复用，否则执行任务并存储结果

差异对比

特性	构建缓存	增量构建
作用范围	跨构建/跨机器	当前构建
存储内容	任务输出归档	输入/输出快照
主要优势	避免重复计算	减少任务执行数量
典型应用	CI 环境共享	本地开发迭代

最佳实践

1. 同时启用两种机制以获得最大性能
2. 对自定义任务正确声明输入/输出
3. 避免在任务中写入随机值或时间戳

---

六、依赖管理

依赖配置（implementation、compileOnly等）

在 Gradle 构建工具中，依赖配置（Dependency Configuration）用于定义项目中依赖项的作用范围和传递性。不同的配置决定了依赖项在编译、测试和运行时的可见性，以及是否会被传递给依赖该项目的其他模块。

常见的依赖配置

1. implementation

   • 定义：当前模块的私有依赖，仅在当前模块内部可见，不会传递给依赖该模块的其他模块。
   • 使用场景：适用于大多数依赖项，尤其是库的内部实现依赖。
   • 优点：减少依赖传递，加快构建速度，避免依赖冲突。
   • 示例：

     dependencies {
         implementation 'com.google.guava:guava:31.1-jre'
     }
     

2. api（旧称 compile）

   • 定义：当前模块的公开依赖，会传递给依赖该模块的其他模块。
   • 使用场景：适用于库的公共接口依赖（如库的 API 中暴露的类型）。
   • 注意：滥用 api 会导致依赖传递链过长，增加构建时间和冲突风险。
   • 示例：

     dependencies {
         api 'org.apache.commons:commons-lang3:3.12.0'
     }
     

3. compileOnly

   • 定义：依赖仅在编译时可用，不会打包到最终输出（如 JAR 或 APK）。
   • 使用场景：
     • 注解处理器（如 Lombok）。
     • 仅编译时需要的库（如代码生成工具）。
   • 示例：

     dependencies {
         compileOnly 'org.projectlombok:lombok:1.18.24'
     }
     

4. runtimeOnly（旧称 runtime）

   • 定义：依赖仅在运行时可用，编译时不可见。
   • 使用场景：
     • 运行时动态加载的库（如 JDBC 驱动）。
     • 与具体实现相关的依赖（如 SLF4J 的绑定库）。
   • 示例：

     dependencies {
         runtimeOnly 'mysql:mysql-connector-java:8.0.28'
     }
     

5. testImplementation

   • 定义：仅在测试代码中可见的依赖。
   • 使用场景：单元测试框架（如 JUnit、Mockito）。
   • 示例：

     dependencies {
         testImplementation 'junit:junit:4.13.2'
     }
     

6. testCompileOnly / testRuntimeOnly

   • 类似于 compileOnly 和 runtimeOnly，但仅作用于测试代码。

依赖配置的选择原则

1. 优先使用 implementation：除非依赖需要暴露给其他模块，否则默认使用 implementation 以减少依赖传递。
2. 谨慎使用 api：仅在依赖项是模块公共接口的一部分时使用。
3. 区分编译时与运行时：
   • 使用 compileOnly 避免将仅需编译的依赖打包到输出。
   • 使用 runtimeOnly 确保依赖仅在运行时加载。

常见误区

1. 混淆 implementation 和 api：

   • 错误地使用 api 会导致依赖传递链膨胀，增加冲突风险。
   • 例如，将工具库（如 Guava）声明为 api 可能污染依赖者的类路径。

2. 误用 compileOnly：

   • 如果 compileOnly 依赖在运行时是必需的（如 Lombok 未配置注解处理器），会导致运行时错误。

3. 忽略测试依赖的作用域：

   • 将测试依赖（如 JUnit）错误地声明为 implementation 会污染生产代码的依赖。

示例对比

假设模块 A 依赖模块 B：

• 如果 B 使用 api 声明依赖 X，则 A 会间接依赖 X。
• 如果 B 使用 implementation 声明依赖 X，则 A 不会感知 X 的存在。

总结

正确选择依赖配置是 Gradle 构建优化的关键。通过合理使用 implementation、api、compileOnly 等配置，可以：

• 减少不必要的依赖传递。
• 加快构建速度。
• 避免类路径冲突。

---

仓库配置（Maven、Ivy等）

概念定义

仓库（Repository）是 Gradle 用于存储和检索依赖项（如 JAR 文件、插件等）的集中存储位置。Gradle 支持多种仓库类型，最常见的是 Maven 仓库 和 Ivy 仓库。仓库可以是本地的（如本地文件系统）或远程的（如 Maven Central、JCenter 或私有仓库服务器）。

主要仓库类型

1. Maven 仓库：

   • 遵循 Maven 的仓库布局规范。
   • 可以是本地仓库（如 ~/.m2/repository）或远程仓库（如 Maven Central、JCenter 或公司私有仓库）。
   • 通过 mavenCentral()、mavenLocal() 或 maven { url } 配置。

2. Ivy 仓库：

   • 遵循 Apache Ivy 的仓库布局规范。
   • 通常用于非 Maven 标准的依赖项或自定义仓库布局。
   • 通过 ivy { url } 配置。

3. Flat Directory 仓库：

   • 简单的文件系统目录，不遵循 Maven 或 Ivy 规范。
   • 通过 flatDir { dirs } 配置。

使用场景

1. 从公共仓库获取依赖：

   • 例如从 Maven Central 或 JCenter 下载开源库。
   • 适用于大多数开源项目。

2. 私有仓库配置：

   • 公司内部可能使用私有仓库（如 Nexus、Artifactory）托管私有依赖。
   • 需要配置仓库 URL 和可能的认证信息。

3. 本地开发与缓存：

   • 使用 mavenLocal() 可以复用本地 Maven 缓存的依赖，避免重复下载。

4. 离线模式：

   • 通过本地仓库或缓存支持离线构建。

配置示例

以下是一个典型的 build.gradle 文件中的仓库配置：

repositories {
    // 1. Maven Central 仓库
    mavenCentral()

    // 2. 本地 Maven 仓库（~/.m2/repository）
    mavenLocal()

    // 3. 自定义 Maven 仓库（如公司私有仓库）
    maven {
        url "https://repo.example.com/releases"
        // 可选：认证信息
        credentials {
            username "user"
            password "password"
        }
    }

    // 4. Ivy 仓库
    ivy {
        url "https://repo.example.com/ivy-repo"
        layout "pattern", {
            artifact "[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"
        }
    }

    // 5. Flat Directory 仓库（本地目录）
    flatDir {
        dirs "libs"
    }
}

常见误区与注意事项

1. 仓库顺序：

   • Gradle 会按声明的顺序检查仓库，直到找到依赖项。将最常用的仓库（如私有仓库）放在前面可以提高构建速度。

2. 认证问题：

   • 私有仓库可能需要认证信息。避免将明文密码提交到版本控制中，建议使用环境变量或 Gradle 属性文件（如 gradle.properties）。

3. 仓库镜像：

   • 在国内访问 Maven Central 可能较慢，可以配置阿里云镜像：

     maven { url "https://maven.aliyun.com/repository/public" }
     

4. 依赖冲突：

   • 如果多个仓库包含相同依赖的不同版本，可能导致冲突。使用 dependencyInsight 任务排查：

     gradle dependencyInsight --dependency <dependency-name>
     

5. 仓库声明位置：

   • 仓库可以在全局（settings.gradle 的 dependencyResolutionManagement）或模块级（build.gradle）配置。全局配置对所有模块生效。

高级配置

1. 仓库过滤：

   • 可以限制仓库仅用于某些依赖：

     repositories {
         maven {
             url "https://repo.example.com/releases"
             content {
                 includeGroup "com.example"
             }
         }
     }
     

2. 仓库元数据缓存：

   • Gradle 会缓存仓库元数据（如 pom 文件）。可以通过 --refresh-dependencies 强制刷新：

     gradle build --refresh-dependencies
     

3. 仓库替换规则：

   • 使用 resolutionStrategy 替换特定依赖的仓库：

     configurations.all {
         resolutionStrategy {
             dependencySubstitution {
                 substitute module("org.old:lib") using module("org.new:lib:1.0")
             }
         }
     }
     

---

依赖冲突解决

什么是依赖冲突

依赖冲突是指项目中的多个依赖项（包括传递性依赖）引入了相同库的不同版本，导致构建或运行时出现异常。例如：

• 项目依赖 libA:1.0 和 libB:2.0，而 libB 又传递依赖 libA:2.0
• 最终可能因版本不一致引发 NoSuchMethodError 或 ClassNotFoundException

常见场景

1. 直接依赖冲突：项目中显式声明了同一个库的多个版本。
2. 传递性依赖冲突：依赖的库间接引入了不同版本的相同依赖。
3. 跨模块冲突：多模块项目中，子模块使用了不同版本的依赖。

解决方案

1. 排除传递性依赖

通过 exclude 移除特定依赖的传递性依赖：

implementation('org.example:libB:2.0') {
    exclude group: 'org.example', module: 'libA' // 排除libB对libA的依赖
}

2. 强制指定版本

在 build.gradle 中统一版本：

configurations.all {
    resolutionStrategy {
        force 'org.example:libA:2.0' // 强制所有依赖使用libA 2.0
    }
}

3. 依赖约束

在 dependencies 块中添加约束（Gradle 5.0+）：

dependencies {
    implementation 'org.example:libB:2.0'
    constraints {
        implementation('org.example:libA:2.0') // 约束libA版本
    }
}

4. 使用新版本优先策略

configurations.all {
    resolutionStrategy {
        preferProjectModules() // 优先使用项目声明的版本
        failOnVersionConflict() // 冲突时直接失败（严格模式）
    }
}

排查工具

1. 依赖树分析：

   gradle dependencies > deps.txt  # 输出依赖树到文件
   

2. 图形化工具：

   gradle build --scan  # 生成HTML报告（需联网）
   

常见误区

1. 盲目排除依赖：可能导致缺失必要的类。
2. 强制版本过低：高版本依赖可能无法兼容低版本API。
3. 忽略测试依赖：测试范围的依赖（如 testImplementation）也可能引发冲突。

最佳实践

1. 使用 implementation 而非 compile（避免泄漏传递依赖）。
2. 定期执行 gradle dependencyUpdates 检查过时依赖。
3. 多模块项目推荐在根 build.gradle 中统一管理版本：

   ext {
       libAVersion = '2.0'
   }
   // 子模块通过 rootProject.libAVersion 引用
   

---

依赖版本管理

什么是依赖版本管理

依赖版本管理是 Gradle 构建工具中用于统一管理项目依赖项版本号的机制。它允许开发者在一个集中位置定义依赖库的版本号，然后在多个模块或构建脚本中引用这些版本号，避免版本号硬编码带来的维护问题。

为什么需要依赖版本管理

1. 一致性：确保项目中使用的相同依赖库版本一致
2. 可维护性：只需修改一处即可更新所有相关依赖版本
3. 减少冲突：避免因版本不一致导致的依赖冲突
4. 可读性：使构建脚本更清晰，关注点分离

实现方式

Gradle 提供了几种方式实现依赖版本管理：

1. 使用 ext 属性（传统方式）

// 在根项目的 build.gradle 中定义版本号
ext {
    springBootVersion = '2.7.0'
    junitVersion = '5.8.2'
}

// 在子模块中引用
dependencies {
    implementation "org.springframework.boot:spring-boot-starter-web:$springBootVersion"
    testImplementation "org.junit.jupiter:junit-jupiter-api:$junitVersion"
}

2. 使用 gradle.properties 文件

# gradle.properties
springBootVersion=2.7.0
junitVersion=5.8.2

// 在构建脚本中引用
dependencies {
    implementation "org.springframework.boot:spring-boot-starter-web:$springBootVersion"
}

3. 使用版本目录（Gradle 7.0+ 推荐方式）

// settings.gradle
dependencyResolutionManagement {
    versionCatalogs {
        libs {
            version('spring-boot', '2.7.0')
            version('junit', '5.8.2')
            
            library('spring-boot-starter-web', 'org.springframework.boot', 'spring-boot-starter-web').versionRef('spring-boot')
            library('junit-jupiter-api', 'org.junit.jupiter', 'junit-jupiter-api').versionRef('junit')
        }
    }
}

// build.gradle
dependencies {
    implementation libs.spring.boot.starter.web
    testImplementation libs.junit.jupiter.api
}

最佳实践

1. 统一管理位置：建议在根项目的 build.gradle 或 gradle.properties 中集中管理
2. 命名规范：使用一致的命名约定，如 camelCase 或 kebab-case
3. 版本别名：为常用依赖定义别名，提高可读性
4. 注释说明：为每个版本号添加注释说明其用途
5. 版本范围：谨慎使用动态版本（如 ‘1.+’）以避免不可预期的更新

常见问题与解决方案

1. 版本冲突：

   • 使用 ./gradlew dependencies 查看依赖树
   • 使用 resolutionStrategy 强制指定版本

2. 缓存问题：

   • 修改版本后执行 ./gradlew --refresh-dependencies

3. 多模块项目同步：

   • 使用版本目录或根项目的 ext 属性确保所有模块使用相同版本

4. 平台依赖管理：

   // 使用平台统一管理相关依赖版本
   implementation platform('org.springframework.boot:spring-boot-dependencies:2.7.0')
   

示例：完整的版本管理配置

// settings.gradle
dependencyResolutionManagement {
    versionCatalogs {
        libs {
            // 定义版本号
            version('spring', '5.3.20')
            version('hibernate', '6.1.0.Final')
            
            // 定义库
            library('spring-core', 'org.springframework', 'spring-core').versionRef('spring')
            library('hibernate-core', 'org.hibernate', 'hibernate-core').versionRef('hibernate')
            
            // 定义插件版本
            plugin('spring-boot', 'org.springframework.boot').version('2.7.0')
        }
    }
}

// build.gradle
plugins {
    alias(libs.plugins.spring.boot)
}

dependencies {
    implementation libs.spring.core
    implementation libs.hibernate.core
}

---

七、插件系统

核心插件介绍

Gradle 的核心插件（Core Plugins）是 Gradle 构建工具自带的一组基础插件，它们提供了构建 Java 项目所需的基本功能。这些插件通常以 java、application、war 等命名，并且不需要额外配置依赖即可直接使用。核心插件的主要目的是简化常见项目的构建配置，例如 Java 应用程序、库或 Web 应用。

常见的核心插件

1. java 插件
   适用于标准的 Java 项目，提供编译、测试和打包 JAR 文件的功能。

   • 定义 src/main/java 和 src/test/java 目录结构。
   • 提供 compileJava、test 和 jar 等任务。

   示例配置：

   plugins {
       id 'java'
   }
   

2. application 插件
   适用于可执行的 Java 应用程序，扩展了 java 插件，并提供了运行和分发功能。

   • 定义 mainClassName 属性指定主类。
   • 提供 run 任务直接运行程序。
   • 生成可分发 ZIP/TAR 包（distZip 和 distTar 任务）。

   示例配置：

   plugins {
       id 'application'
   }
   application {
       mainClassName = 'com.example.Main'
   }
   

3. war 插件
   适用于 Java Web 应用程序（Servlet 项目），扩展了 java 插件，并支持生成 WAR 文件。

   • 定义 src/main/webapp 目录存放 Web 资源（如 JSP、HTML）。
   • 提供 war 任务打包 Web 应用。

   示例配置：

   plugins {
       id 'war'
   }
   

4. java-library 插件
   适用于 Java 库项目，扩展了 java 插件，并支持 API 和实现分离。

   • 区分 api 和 implementation 依赖，优化编译和运行时类路径。

   示例配置：

   plugins {
       id 'java-library'
   }
   dependencies {
       api 'org.apache.commons:commons-lang3:3.12.0'
       implementation 'com.google.guava:guava:30.1.1-jre'
   }
   

使用场景

• java 插件：适用于纯 Java 库或工具项目。
• application 插件：适用于带主类的可执行程序（如命令行工具）。
• war 插件：适用于传统的 Java Web 项目（如 Servlet/JSP）。
• java-library 插件：适用于需要明确区分公开 API 和内部实现的库项目。

常见误区

1. 混淆 java 和 java-library

   • java 插件不区分 api 和 implementation 依赖，可能导致依赖泄漏。
   • 库项目应优先使用 java-library 插件。

2. 忽略 mainClassName 配置

   • 使用 application 插件时，必须指定 mainClassName，否则 run 任务会失败。

3. 误用 war 插件

   • war 插件仅适用于传统 Web 项目，现代 Spring Boot 项目通常使用 jar 打包。

示例：完整构建脚本

以下是一个使用 java-library 插件的完整示例：

plugins {
    id 'java-library'
}

repositories {
    mavenCentral()
}

dependencies {
    api 'org.apache.commons:commons-math3:3.6.1'
    implementation 'com.google.code.gson:gson:2.8.9'
    testImplementation 'junit:junit:4.13.2'
}

tasks.named('test') {
    useJUnitPlatform()
}

---

第三方插件使用

概念定义

Gradle 第三方插件是指由 Gradle 社区或第三方开发者提供的、用于扩展 Gradle 功能的模块。这些插件通常封装了特定的构建逻辑、任务或配置，帮助开发者简化构建流程。例如，java 插件用于 Java 项目构建，spring-boot 插件用于 Spring Boot 项目。

使用场景

1. 功能扩展：为项目添加特定功能（如代码检查、Docker 镜像打包）。
2. 标准化构建：遵循行业标准（如 Java 项目的 java 插件）。
3. 简化配置：减少重复代码（如 spring-boot 插件自动配置主类）。

插件分类

1. 核心插件：Gradle 官方提供（如 java、application）。
2. 社区插件：托管在 Gradle Plugin Portal（如 com.github.spotbugs）。
3. 本地自定义插件：开发者自行编写。

使用方法

方式 1：通过 plugins DSL（推荐）

在 build.gradle 中声明：

plugins {
    id 'java' // 核心插件
    id 'org.springframework.boot' version '3.1.0' // 社区插件（需指定版本）
}

方式 2：通过 buildscript（传统方式）

buildscript {
    repositories {
        gradlePluginPortal() // 或 mavenCentral()
    }
    dependencies {
        classpath 'org.springframework.boot:spring-boot-gradle-plugin:3.1.0'
    }
}
apply plugin: 'org.springframework.boot'

常见插件示例

1. Java 项目：

   plugins {
       id 'java'
   }
   

2. Spring Boot：

   plugins {
       id 'org.springframework.boot' version '3.1.0'
   }
   

3. Docker 打包：

   plugins {
       id 'com.bmuschko.docker-java-application' version '7.4.0'
   }
   

注意事项

1. 版本兼容性：插件版本需与 Gradle 版本兼容（如 Spring Boot 插件 3.x 需 Gradle 7.x+）。
2. 插件冲突：避免多个插件定义相同任务（如 jar 任务）。
3. 仓库配置：社区插件需确保 gradlePluginPortal() 在 repositories 中。
4. 性能影响：过多插件可能增加构建时间。

查找插件

1. 官方插件列表：Gradle Plugin Portal
2. 搜索语法：gradle plugin [功能关键词]（如 “gradle plugin docker”）

---

自定义插件基础

什么是 Gradle 自定义插件

Gradle 自定义插件是用户根据项目需求编写的可复用构建逻辑模块。它允许你将常用的构建逻辑封装起来，供多个项目共享或在不同构建阶段调用。插件可以包含任务定义、依赖管理、文件操作等任何 Gradle 支持的操作。

为什么需要自定义插件

1. 逻辑复用：避免在多个项目中重复编写相同的构建逻辑
2. 代码组织：将复杂构建逻辑分解为模块化组件
3. 团队协作：统一团队的构建标准和流程
4. 功能扩展：为 Gradle 添加原生不支持的功能

创建自定义插件的三种方式

1. 构建脚本中直接编写（简单但不可复用）
2. buildSrc 项目（项目内复用）
3. 独立插件项目（跨项目复用）

构建脚本内插件示例

// 在 build.gradle 中直接定义
class GreetingPlugin implements Plugin<Project> {
    void apply(Project project) {
        project.task('hello') {
            doLast {
                println 'Hello from custom plugin!'
            }
        }
    }
}

// 应用插件
apply plugin: GreetingPlugin

buildSrc 方式创建插件

1. 在项目根目录创建 buildSrc 文件夹

2. 标准目录结构：

   buildSrc/
   ├── build.gradle
   └── src/main/groovy/
       └── com/example/
           └── MyPlugin.groovy
   

3. 示例插件代码：

package com.example

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

class MyPlugin implements Plugin<Project> {
    void apply(Project project) {
        project.extensions.create("myPluginConfig", MyPluginExtension)
        project.task('customTask') {
            doLast {
                println "Message: ${project.myPluginConfig.message}"
            }
        }
    }
}

class MyPluginExtension {
    String message = 'Default message'
}

4. 在 build.gradle 中应用：

plugins {
    id 'com.example.my-plugin'
}

myPluginConfig {
    message = 'Custom configuration'
}

独立插件项目

1. 使用 gradle init 选择 Gradle Plugin 类型

2. 主要文件结构：

   src/main/groovy/
   └── com/example/
       ├── MyPlugin.groovy
       └── MyPluginExtension.groovy
   

3. 需要发布到仓库（Maven Local 或远程仓库）

插件扩展机制

通过扩展对象实现可配置的插件：

// 定义扩展
class MyExtension {
    String target = 'World'
}

// 在插件中使用扩展
class MyPlugin implements Plugin<Project> {
    void apply(Project project) {
        def extension = project.extensions.create('mySettings', MyExtension)
        
        project.task('greet') {
            doLast {
                println "Hello, ${extension.target}!"
            }
        }
    }
}

插件开发最佳实践

1. 遵循命名规范：使用反向域名（如 com.example.plugin）
2. 提供清晰文档：说明插件的功能、用法和配置选项
3. 处理插件依赖：正确声明对其他插件的依赖
4. 版本兼容性：考虑不同 Gradle 版本的兼容性
5. 单元测试：为插件编写测试用例

常见问题解决

1. 插件未找到：确保插件已正确发布和应用
2. 类路径问题：检查依赖是否正确定义
3. 扩展属性无效：确保在应用插件后才配置扩展
4. 任务冲突：避免定义与现有任务同名的任务

高级技巧

1. 使用 PluginAware API 处理不同作用域
2. 通过 ServiceRegistry 共享服务
3. 利用 ObjectFactory 创建配置对象
4. 实现 TaskContainer 进行任务管理

---

插件发布与共享

什么是 Gradle 插件发布与共享

Gradle 插件发布与共享是指将自定义开发的 Gradle 插件打包并发布到公共或私有仓库，以便其他项目或开发者能够方便地引用和使用。通过发布插件，可以实现代码复用、标准化构建流程以及团队协作。

发布插件的步骤

1. 准备工作

确保插件项目已经正确配置，并且已经通过测试。插件项目通常需要包含以下内容：

• build.gradle 或 build.gradle.kts 文件
• 插件实现类
• 插件标识（如 plugin id）

2. 配置发布插件

在插件的 build.gradle 文件中，添加 maven-publish 插件，并配置发布信息：

plugins {
    id 'java-gradle-plugin'
    id 'maven-publish'
}

group 'com.example'
version '1.0.0'

publishing {
    publications {
        maven(MavenPublication) {
            from components.java
        }
    }
    repositories {
        maven {
            url = uri("https://your-repo-url.com/repository/maven-releases/")
            credentials {
                username = project.findProperty("repoUsername") ?: ""
                password = project.findProperty("repoPassword") ?: ""
            }
        }
    }
}

3. 发布到仓库

运行以下命令将插件发布到配置的仓库：

./gradlew publish

共享插件的常见方式

1. 发布到 Maven 仓库

• 公共仓库：如 Maven Central 或 JCenter（已弃用）。
• 私有仓库：如 Nexus 或 Artifactory。

2. 发布到 Gradle 插件门户

Gradle 提供了一个官方的插件门户（Gradle Plugin Portal），开发者可以将插件发布到这里，供全球用户使用。

发布到 Gradle 插件门户的步骤：

1. 在 build.gradle 中配置 gradlePlugin 块：

gradlePlugin {
    plugins {
        myPlugin {
            id = 'com.example.myplugin'
            implementationClass = 'com.example.MyPlugin'
        }
    }
}

2. 使用 gradle-plugin-publish 插件：

plugins {
    id 'com.gradle.plugin-publish' version '1.1.0'
}

3. 配置插件门户的发布信息：

pluginBundle {
    website = 'https://example.com'
    vcsUrl = 'https://github.com/example/myplugin'
    tags = ['gradle', 'plugin', 'example']
}

4. 运行发布命令：

./gradlew publishPlugins

3. 本地共享

如果只是临时共享给团队成员，可以将插件打包到本地 Maven 仓库：

./gradlew publishToMavenLocal

其他开发者可以通过在 settings.gradle 或 build.gradle 中引用本地仓库来使用插件：

pluginManagement {
    repositories {
        mavenLocal()
        gradlePluginPortal()
    }
}

注意事项

1. 插件 ID 唯一性：发布到 Gradle 插件门户时，插件 ID 必须是全局唯一的。通常使用反向域名（如 com.example.myplugin）来避免冲突。

2. 版本管理：遵循语义化版本控制（SemVer），确保版本号清晰表达插件的变更（如 MAJOR.MINOR.PATCH）。

3. 依赖管理：确保插件的依赖范围正确，避免传递依赖冲突。可以使用 api 或 implementation 来明确依赖关系。

4. 文档与示例：发布插件时，提供清晰的文档和示例代码，帮助其他开发者快速上手。

5. 兼容性：注明插件支持的 Gradle 版本和 Java 版本，避免用户在不兼容的环境中使用。

示例：发布一个简单的插件

以下是一个简单的插件发布示例：

1. 插件实现类：

package com.example;

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

public class MyPlugin implements Plugin<Project> {
    @Override
    public void apply(Project project) {
        project.task("hello").doLast(task -> {
            System.out.println("Hello from MyPlugin!");
        });
    }
}

2. build.gradle 配置：

plugins {
    id 'java-gradle-plugin'
    id 'maven-publish'
}

gradlePlugin {
    plugins {
        myPlugin {
            id = 'com.example.myplugin'
            implementationClass = 'com.example.MyPlugin'
        }
    }
}

group 'com.example'
version '1.0.0'

publishing {
    repositories {
        maven {
            url = uri("https://your-repo-url.com/repository/maven-releases/")
            credentials {
                username = project.findProperty("repoUsername")
                password = project.findProperty("repoPassword")
            }
        }
    }
}

3. 发布命令：

./gradlew publish

---

八、多项目构建

多项目结构

概念定义

多项目结构（Multi-Project Build）是指在一个 Gradle 构建中包含多个相互关联的子项目（subprojects），这些子项目可以独立构建，也可以作为整体的一部分协同工作。多项目结构通常用于大型项目或模块化开发，允许开发者将代码拆分为逻辑上独立的模块，每个模块可以有自己的构建配置和依赖关系。

使用场景

1. 模块化开发：将大型项目拆分为多个子模块（如核心模块、业务模块、测试模块等），便于团队协作和代码管理。
2. 代码复用：多个子项目可以共享公共代码或依赖（如工具类库、配置等）。
3. 独立构建：子项目可以单独构建和测试，提高开发效率。
4. 依赖管理：子项目之间可以定义依赖关系（如 app 模块依赖 core 模块）。

目录结构示例

一个典型的多项目结构目录如下：

root-project/
├── build.gradle           // 根项目的构建脚本
├── settings.gradle        // 定义包含的子项目
├── core/                  // 子项目1
│   ├── build.gradle
│   └── src/
├── app/                   // 子项目2
│   ├── build.gradle
│   └── src/
└── shared/                // 子项目3
    ├── build.gradle
    └── src/

关键配置

1. settings.gradle
   在根项目的 settings.gradle 中声明包含的子项目：

   include ':core', ':app', ':shared'
   

   • include 用于指定子项目的路径。
   • 子项目的路径是相对于根项目的目录（如 :core 对应 core/ 目录）。

2. 根项目的 build.gradle
   可以定义所有子项目的公共配置（通过 subprojects 或 allprojects）：

   subprojects {
       apply plugin: 'java'
       repositories {
           mavenCentral()
       }
   }
   

3. 子项目的 build.gradle
   每个子项目可以有自己的构建配置。例如，app 模块依赖 core 模块：

   dependencies {
       implementation project(':core')
   }
   

常见误区

1. 路径错误

   • 在 settings.gradle 中声明的子项目路径必须与实际目录一致。
   • 错误示例：目录名为 core-module，但 settings.gradle 中写为 include ':core'。

2. 循环依赖

   • 子项目之间不能形成循环依赖（如 A 依赖 B，B 又依赖 A），否则构建会失败。

3. 配置泄露

   • 避免在根项目的 build.gradle 中过度使用 allprojects，否则可能将不必要的配置应用到所有子项目。

高级用法

1. 项目依赖替换
   如果子项目依赖外部库，但在多项目构建中希望替换为本地子项目，可以使用依赖替换：

   configurations.all {
       resolutionStrategy.dependencySubstitution {
           substitute module('com.example:core') with project(':core')
       }
   }
   

2. 自定义构建逻辑
   可以通过 gradle.projectsEvaluated 在构建完成后执行自定义逻辑：

   gradle.projectsEvaluated {
       subprojects {
           // 检查所有子项目的配置
       }
   }
   

示例代码

以下是一个完整的多项目构建配置示例：

1. settings.gradle

   rootProject.name = 'multi-project-demo'
   include ':core', ':app'
   

2. 根项目的 build.gradle

   plugins {
       id 'base'
   }
   
   subprojects {
       apply plugin: 'java'
       repositories {
           mavenCentral()
       }
   }
   

3. core/build.gradle

   dependencies {
       implementation 'org.apache.commons:commons-lang3:3.12.0'
   }
   

4. app/build.gradle

   dependencies {
       implementation project(':core')
   }
   

---

子项目配置

概念定义

子项目配置（Subproject Configuration）是 Gradle 多项目构建（Multi-project Build）中的核心概念，用于管理包含多个子模块的项目结构。通过子项目配置，可以在父项目中统一管理所有子项目的构建逻辑、依赖关系和共享配置。

使用场景

1. 模块化开发：将大型项目拆分为多个子模块（如 core、web、utils 等），每个子模块独立开发。
2. 共享配置：在父项目中定义公共插件、依赖或属性，避免子项目重复配置。
3. 依赖管理：子项目之间可以相互引用（如 web 依赖 core）。

配置方式

1. 项目结构

典型的目录结构如下：

root-project/
├── build.gradle           // 父项目构建脚本
├── settings.gradle        // 定义子项目
├── core/
│   └── build.gradle       // 子项目配置
└── web/
    └── build.gradle

2. settings.gradle 声明子项目

include ':core', ':web'  // 包含子项目

3. 父项目统一配置（build.gradle）

通过 subprojects 或 allprojects 块对所有子项目应用配置：

subprojects {
    // 公共插件
    apply plugin: 'java'
    
    // 公共依赖
    repositories {
        mavenCentral()
    }
    
    // 自定义属性
    ext {
        lombokVersion = '1.18.24'
    }
}

4. 子项目特定配置（web/build.gradle）

dependencies {
    implementation project(':core')  // 依赖其他子项目
    implementation 'org.springframework:spring-web:5.3.0'
}

常见误区

1. 循环依赖：子项目之间相互引用（如 A 依赖 B，B 又依赖 A）会导致构建失败。
2. 过度共享配置：在 allprojects 中配置非必要的属性可能污染所有子项目。
3. 路径错误：在 settings.gradle 中使用错误的子项目路径（如 include ':wrong-path'）。

高级技巧

条件化配置

通过 project 对象判断子项目名称，动态调整配置：

subprojects {
    if (project.name == 'web') {
        apply plugin: 'war'
    }
}

跨项目属性访问

在子项目中访问父项目定义的属性：

// 父项目 build.gradle
ext.sharedVersion = '1.0'

// 子项目 build.gradle
version = rootProject.ext.sharedVersion

---

项目间依赖

概念定义

项目间依赖（Inter-project Dependencies）指的是在 Gradle 构建系统中，一个项目（Project）依赖于另一个项目的输出（如 JAR 文件、类文件或其他构建产物）。这种依赖关系允许在多模块项目中，模块之间相互引用，实现代码复用和模块化开发。

使用场景

1. 多模块项目：当一个项目被拆分为多个子模块时，子模块之间可能需要相互依赖。例如，一个 core 模块提供基础功能，而 web 模块依赖于 core 模块。
2. 代码复用：通过将公共代码提取到独立的项目中，其他项目可以直接依赖它，避免重复代码。
3. 构建优化：Gradle 可以识别项目间依赖，并优化构建顺序，仅重新构建受影响的模块。

配置方式

在 Gradle 中，项目间依赖通常通过 settings.gradle 和 build.gradle 文件配置。

1. 定义多项目结构

在 settings.gradle 中声明包含的子项目：

include 'core', 'web'

2. 声明依赖关系

在依赖方的 build.gradle 文件中（例如 web 模块），通过 project() 方法声明对另一个项目（如 core）的依赖：

dependencies {
    implementation project(':core')
}

注意事项

1. 循环依赖：避免项目 A 依赖项目 B，同时项目 B 又依赖项目 A，这会导致构建失败。
2. 依赖传递性：项目间依赖默认是传递的。如果项目 A 依赖项目 B，而项目 B 依赖库 X，那么项目 A 也会间接依赖库 X。
3. 构建顺序：Gradle 会自动根据依赖关系确定构建顺序，确保被依赖的项目先构建。
4. 项目路径：在 project() 方法中使用的路径（如 :core）必须与 settings.gradle 中定义的名称一致。

示例

假设有一个多模块项目结构如下：

my-project/
├── settings.gradle
├── core/
│   └── build.gradle
└── web/
    └── build.gradle

settings.gradle

rootProject.name = 'my-project'
include 'core', 'web'

core/build.gradle

plugins {
    id 'java'
}

dependencies {
    // core 模块的依赖
}

web/build.gradle

plugins {
    id 'java'
}

dependencies {
    implementation project(':core') // 依赖 core 模块
}

高级用法

1. 依赖特定配置：可以通过 project(path, configuration) 指定依赖的配置（如 testFixtures）：

   dependencies {
       testImplementation project(path: ':core', configuration: 'testFixtures')
   }
   

2. 条件依赖：根据条件动态添加项目依赖：

   dependencies {
       if (someCondition) {
           implementation project(':moduleA')
       } else {
           implementation project(':moduleB')
       }
   }
   

通过合理使用项目间依赖，可以更好地组织大型项目的代码结构，提高构建效率和可维护性。

---

共享构建逻辑

概念定义

共享构建逻辑（Shared Build Logic）是指将 Gradle 构建脚本中重复使用的配置、任务或插件逻辑提取出来，封装成可复用的模块。通过这种方式，可以避免代码重复，提高构建脚本的可维护性和一致性。

使用场景

1. 多模块项目：在包含多个子模块的项目中，共享构建逻辑可以确保所有模块使用相同的配置（如编译器选项、依赖版本等）。
2. 跨项目复用：在多个独立项目中共享通用的构建逻辑（如代码风格检查、测试配置等）。
3. 团队协作：统一团队的构建标准，减少配置差异。

实现方式

Gradle 提供了多种方式实现共享构建逻辑：

1. 使用 buildSrc 目录

buildSrc 是 Gradle 的约定目录，用于存放构建逻辑的源代码。Gradle 会自动编译并将其添加到构建脚本的类路径中。

示例

project-root/
├── buildSrc/
│   ├── src/main/java/com/example/MyCustomPlugin.java
│   └── build.gradle
├── app/
│   └── build.gradle
└── settings.gradle

在 buildSrc/build.gradle 中定义插件：

plugins {
    id 'java-gradle-plugin'
}

gradlePlugin {
    plugins {
        myPlugin {
            id = 'com.example.myplugin'
            implementationClass = 'com.example.MyCustomPlugin'
        }
    }
}

在子模块中使用：

plugins {
    id 'com.example.myplugin'
}

2. 使用复合构建（Composite Builds）

通过 includeBuild 将另一个 Gradle 项目作为插件引入。

示例

在 settings.gradle 中：

includeBuild 'shared-build-logic'

3. 使用预编译脚本插件

将共享逻辑写入 .gradle 文件，然后通过 apply from 引入。

示例

创建 shared-config.gradle：

android {
    compileSdkVersion 33
    defaultConfig {
        minSdkVersion 21
    }
}

在模块中引入：

apply from: "$rootDir/shared-config.gradle"

常见误区

1. 过度共享：将不相关的逻辑强制共享，反而增加复杂度。
2. 版本冲突：共享逻辑中使用的依赖版本可能与项目冲突，需统一管理。
3. 循环依赖：buildSrc 不能依赖主项目的代码。

最佳实践

1. 优先使用 buildSrc 或复合构建，而非脚本插件（后者难以维护）。
2. 为共享逻辑编写测试。
3. 使用版本目录（Version Catalogs）统一管理依赖版本。

---

九、构建优化

构建缓存（Build Cache）

概念定义

构建缓存是 Gradle 的核心功能之一，它通过缓存任务输出（如编译后的类文件、生成的资源文件等）来加速后续构建过程。当 Gradle 检测到输入（如源代码、依赖项）未发生变化时，会直接复用缓存中的结果，避免重复执行相同的任务。

工作原理

1. 缓存键（Cache Key）：Gradle 为每个任务生成唯一的缓存键，基于：
   • 任务类型
   • 输入文件内容（如源代码的哈希值）
   • 类路径依赖的版本
   • 任务配置参数
2. 缓存存储：支持本地缓存（默认在 ~/.gradle/caches）和远程缓存（如团队共享的 CI 服务器缓存）。
3. 缓存命中：当输入和配置相同时，直接复用缓存结果。

使用场景

1. 本地开发：加速增量构建（如 gradle build 的第二次运行）。
2. CI/CD 流水线：通过共享远程缓存，减少不同机器或分支的重复构建。
3. 多模块项目：避免未更改的模块重复构建。

配置示例

在 gradle.properties 中启用本地缓存：

org.gradle.caching=true

或在 settings.gradle 中配置远程缓存：

buildCache {
    remote(HttpBuildCache) {
        url = 'https://cache.example.com'
        credentials {
            username = 'user'
            password = 'secret'
        }
    }
}

注意事项

1. 缓存失效：
   • 输入变化（如修改代码）会自动失效。
   • 非确定性任务（如依赖当前时间的任务）需显式声明为不可缓存：

     tasks.register("nonCacheableTask") {
         outputs.doNotCacheIf("Has random output") { true }
     }
     

2. 存储成本：大型项目可能占用大量磁盘空间，需定期清理（gradle cleanBuildCache）。
3. 安全性：远程缓存需确保传输加密（HTTPS）和访问控制。

常见误区

1. 误认为缓存替代增量构建：缓存是增量构建的补充，而非替代。
2. 忽略缓存键的输入范围：未将动态资源（如环境变量）纳入输入声明会导致错误缓存。
3. 过度依赖远程缓存：网络延迟可能抵消缓存收益，建议本地缓存优先。

---

并行构建

概念定义

并行构建（Parallel Build）是指 Gradle 在构建过程中同时执行多个独立的任务，以充分利用多核 CPU 的计算能力，从而显著缩短构建时间。Gradle 通过分析任务之间的依赖关系图，自动识别可以并行执行的任务。

工作原理

1. 依赖分析：Gradle 会构建任务依赖图，确定哪些任务可以并行执行（无依赖关系的任务）。
2. 线程池管理：默认使用 java.util.concurrent 线程池，任务会被分配到不同线程。
3. 资源控制：通过 org.gradle.workers.max 参数限制最大并行线程数。

启用方式

在 gradle.properties 中配置：

# 启用并行构建
org.gradle.parallel=true
# 可选：设置最大并行线程数（默认为CPU核心数）
org.gradle.workers.max=4

或通过命令行参数：

./gradlew build --parallel --max-workers=4

适用场景

1. 多模块项目：子模块间无依赖时效果最佳
2. 独立任务：如同时编译多个子项目的Java代码
3. CPU密集型操作：代码编译、测试执行等

注意事项

1. 任务依赖性：并行构建要求任务正确声明输入/输出和依赖关系，否则可能导致竞态条件。
2. 共享资源冲突：避免多个任务同时修改同一文件（如日志文件）。
3. 测试任务：某些测试框架（如JUnit）可能不支持并行执行测试类。
4. 内存消耗：并行构建会增加内存使用量，需调整JVM参数：

   org.gradle.jvmargs=-Xmx2g
   

性能优化建议

1. 使用 --profile 参数生成构建报告，分析并行效果：

   ./gradlew build --parallel --profile
   

2. 通过 --dry-run 查看任务执行顺序：

   ./gradlew build --parallel --dry-run
   

3. 对I/O密集型任务（如文件复制）使用 @ParallelizableTask 注解。

示例对比

假设项目结构：

project
├── moduleA
├── moduleB
└── moduleC

串行构建时序：

:moduleA:compileJava -> :moduleB:compileJava -> :moduleC:compileJava

并行构建时序：

:moduleA:compileJava
:moduleB:compileJava  ← 同时执行
:moduleC:compileJava

常见问题

1. 构建失败不稳定：可能是任务未正确声明依赖，需检查 dependsOn 和 mustRunAfter。
2. 日志混乱：建议使用 --console=plain 参数：

   ./gradlew build --parallel --console=plain
   

3. 缓存问题：并行构建可能加剧缓存竞争，可配置独立缓存目录：

   org.gradle.caching=true
   org.gradle.cache.key=hash(${projectDir})
   

---

增量构建

概念定义

增量构建（Incremental Build）是构建工具（如 Gradle）的一种优化机制，指在项目构建过程中仅重新编译或处理发生变化的源文件，而非每次都执行完整的构建流程。Gradle 通过智能的任务依赖分析和输入/输出跟踪，自动跳过未变更的任务，显著提升构建效率。

工作原理

1. 输入/输出快照：Gradle 记录每个任务的输入文件（如源代码）和输出文件（如编译后的类文件）的哈希值。
2. 变更检测：再次构建时，对比当前输入文件的哈希值与上次构建的快照。
3. 任务跳过：若输入未变化且输出已存在，则跳过该任务执行；否则执行任务并更新快照。

使用场景

• 开发阶段：频繁修改代码后快速验证变更。
• 大型项目：减少数百个模块的重复编译时间。
• 持续集成：在代码库部分更新时加速流水线。

示例代码

通过 inputs 和 outputs 显式声明任务的增量特性：

task processTemplates(type: Copy) {
    inputs.property("version", project.version) // 输入属性
    from 'src/templates'
    into 'build/processed'
    expand(version: project.version) // 使用动态内容
    outputs.upToDateWhen { !source.empty } // 输出条件
}

常见误区与注意事项

1. 非幂等任务：若任务逻辑依赖外部状态（如当前时间），需禁用增量：

   tasks.named("generateReport") {
       outputs.upToDateWhen { false } // 强制每次执行
   }
   

2. 文件路径变化：移动或重命名输入文件会被视为新文件，触发重新构建。
3. 动态依赖：通过 dependsOn 动态添加的任务可能破坏增量性。
4. 缓存清理：执行 clean 任务会清除所有输出，导致下次全量构建。

调试技巧

1. 查看任务跳过原因：

   gradle build --info | grep "UP-TO-DATE"
   

2. 强制全量构建：

   gradle build --rerun-tasks
   

3. 检查任务输入输出：

   gradle :taskName --console=verbose
   

---

性能监控与调优

概念定义

性能监控与调优是指通过工具和技术手段，对应用程序的运行状态进行实时或定期监测，分析性能瓶颈，并采取优化措施以提高系统响应速度、资源利用率和整体性能的过程。

使用场景

1. 开发阶段：在本地开发环境中进行初步性能测试和优化。
2. 测试阶段：通过压力测试、负载测试等发现性能问题。
3. 生产环境：实时监控线上系统性能，及时发现并解决性能问题。

常见监控指标

1. CPU 使用率：反映系统处理能力是否饱和。
2. 内存使用情况：包括堆内存、非堆内存的使用情况。
3. 线程状态：线程数量、阻塞线程、死锁情况等。
4. GC 情况：垃圾回收频率、耗时等。
5. I/O 操作：磁盘和网络 I/O 的吞吐量和延迟。

常用工具

1. JVM 自带工具：

   • jps：查看 Java 进程
   • jstat：监控 JVM 统计信息
   • jstack：获取线程堆栈
   • jmap：生成堆转储快照
   • jconsole：图形化监控工具
   • VisualVM：功能更强大的图形化工具

2. 第三方工具：

   • Arthas：阿里开源的 Java 诊断工具
   • Prometheus + Grafana：监控和可视化
   • SkyWalking、Pinpoint：分布式追踪系统

性能调优方法

1. JVM 调优：

   • 调整堆内存大小（-Xms, -Xmx）
   • 选择合适的垃圾收集器（如 G1、ZGC）
   • 优化 GC 参数（如 -XX:MaxGCPauseMillis）

2. 代码优化：

   • 减少对象创建
   • 使用缓存
   • 优化循环和算法
   • 避免频繁的 I/O 操作

3. 数据库优化：

   • 添加合适的索引
   • 优化 SQL 查询
   • 使用连接池

4. 并发优化：

   • 合理使用线程池
   • 减少锁竞争
   • 使用并发集合

示例代码（使用 VisualVM 监控）

public class PerformanceTest {
    public static void main(String[] args) {
        // 模拟内存泄漏
        List<byte[]> list = new ArrayList<>();
        while (true) {
            byte[] data = new byte[1024 * 1024]; // 1MB
            list.add(data);
            try {
                Thread.sleep(100);
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
        }
    }
}

常见误区与注意事项

1. 过早优化：不要在没有明确性能问题的情况下进行优化。
2. 过度优化：优化可能会增加代码复杂度，需权衡利弊。
3. 忽略基准测试：优化前后应进行基准测试以验证效果。
4. 仅关注单一指标：需要综合考虑 CPU、内存、I/O 等多个方面。
5. 忽视生产环境差异：测试环境和生产环境的性能表现可能有很大不同。

性能调优流程

1. 发现问题：通过监控或用户反馈发现性能问题。
2. 分析定位：使用工具定位性能瓶颈。
3. 制定方案：根据分析结果制定优化方案。
4. 实施优化：实施优化措施。
5. 验证效果：通过测试验证优化效果。
6. 持续监控：上线后持续监控性能变化。

---

十、实际应用示例

Java 项目构建示例

基本项目结构

一个标准的 Gradle Java 项目通常包含以下目录结构：

project-root/
├── build.gradle
├── settings.gradle
├── gradlew
├── gradlew.bat
└── src/
    ├── main/
    │   ├── java/       # 主 Java 源代码
    │   └── resources/  # 主资源文件
    └── test/
        ├── java/       # 测试 Java 源代码
        └── resources/  # 测试资源文件

基础 build.gradle 示例

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

group 'com.example'  // 项目组标识
version '1.0.0'      // 项目版本

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

dependencies {
    implementation 'org.apache.commons:commons-lang3:3.12.0'  // 主代码依赖
    testImplementation 'junit:junit:4.13.2'                  // 测试代码依赖
}

多模块项目示例

在 settings.gradle 中定义模块：

rootProject.name = 'my-project'
include 'core', 'web', 'utils'

每个子模块有自己的 build.gradle，例如 core/build.gradle：

plugins {
    id 'java-library'  // 适用于库模块
}

dependencies {
    api project(':utils')  // 暴露给其他模块的依赖
    implementation 'com.google.guava:guava:31.1-jre'
}

自定义任务示例

task generateReport(type: JavaExec) {
    classpath = sourceSets.main.runtimeClasspath
    mainClass = 'com.example.ReportGenerator'
    args '--output', 'build/reports'
}

// 将自定义任务绑定到构建生命周期
build.dependsOn generateReport

构建命令示例

常用 Gradle 命令：

# 编译并运行测试
./gradlew build

# 只运行单元测试
./gradlew test

# 生成项目依赖树
./gradlew dependencies

# 清理构建产物
./gradlew clean

# 运行特定任务
./gradlew generateReport

常见构建场景

1. 打包可执行 JAR：

jar {
    manifest {
        attributes 'Main-Class': 'com.example.Main'
    }
    from {
        configurations.runtimeClasspath.collect {
            it.isDirectory() ? it : zipTree(it)
        }
    }
}

2. 排除特定依赖：

dependencies {
    implementation('org.library:some-lib:1.0') {
        exclude group: 'com.unwanted', module: 'deprecated-module'
    }
}

3. 多环境构建：

sourceSets {
    prod {
        java.srcDirs = ['src/prod/java']
    }
    staging {
        java.srcDirs = ['src/staging/java']
    }
}

注意事项

1. 依赖声明时：

   • implementation：仅当前模块可见
   • api：会传递给依赖该模块的其他模块
   • compileOnly：仅编译时可用

2. 构建缓存：

   • 默认启用缓存（~/.gradle/caches）
   • 可通过 --build-cache 启用远程缓存

3. 性能优化：

   • 使用 --parallel 并行构建
   • 使用 --daemon 守护进程减少启动时间

---

Web 项目构建示例

1. 什么是 Web 项目构建？

Web 项目构建是指使用构建工具（如 Gradle）将 Web 应用程序的源代码、资源文件和依赖项编译、打包并部署为可运行的 Web 应用程序的过程。通常包括以下步骤：

• 编译 Java 代码
• 处理静态资源（如 HTML、CSS、JavaScript）
• 打包为 WAR（Web Application Archive）或 JAR（带有嵌入式容器的 Spring Boot 项目）
• 运行测试
• 部署到服务器或容器

2. 使用 Gradle 构建 Web 项目的场景

• 传统的 Java EE Web 应用（Servlet/JSP）
• 基于 Spring Boot 的现代 Web 应用
• 前后端分离项目中的后端服务
• 微服务架构中的单个服务模块

3. 基础 Web 项目构建示例

3.1 传统 WAR 项目

plugins {
    id 'war'  // 应用 war 插件
    id 'java'
}

repositories {
    mavenCentral()
}

dependencies {
    // Servlet API 依赖
    providedCompile 'javax.servlet:javax.servlet-api:4.0.1'
    
    // 其他依赖
    implementation 'org.apache.commons:commons-lang3:3.12.0'
}

war {
    archiveFileName = 'mywebapp.war'  // 指定生成的 WAR 文件名
    from 'src/main/webapp'  // 包含 webapp 目录内容
}

3.2 Spring Boot Web 项目

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.1.0'
    id 'io.spring.dependency-management' version '1.1.0'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

bootJar {
    archiveFileName = 'app.jar'  // 指定生成的 JAR 文件名
}

4. 多模块 Web 项目构建

// settings.gradle
include 'web', 'service', 'repository'

// web/build.gradle
plugins {
    id 'war'
}

dependencies {
    implementation project(':service')  // 依赖其他模块
    providedCompile 'javax.servlet:javax.servlet-api:4.0.1'
}

5. 常见构建任务

• gradle build - 执行完整构建（编译、测试、打包）
• gradle war - 仅构建 WAR 文件（传统项目）
• gradle bootRun - 运行 Spring Boot 应用
• gradle test - 运行测试
• gradle clean - 清理构建目录

6. 高级配置示例

6.1 环境特定配置

war {
    // 根据环境包含不同的配置文件
    def env = System.getProperty('env') ?: 'dev'
    from("src/main/environments/$env") {
        into 'WEB-INF/classes'
    }
}

6.2 前端资源处理

task copyFrontend(type: Copy) {
    from 'frontend/dist'
    into 'src/main/webapp/static'
}

war.dependsOn copyFrontend

7. 常见问题与解决方案

1. 依赖冲突：

   • 使用 gradle dependencies 查看依赖树
   • 使用 exclude 排除冲突依赖：

     implementation('org.springframework.boot:spring-boot-starter-web') {
         exclude group: 'org.springframework.boot', module: 'spring-boot-starter-tomcat'
     }
     

2. 构建速度慢：

   • 启用构建缓存：settings.gradle 中添加 enableFeaturePreview('BUILD_CACHE')
   • 使用 Gradle Daemon
   • 配置并行构建：org.gradle.parallel=true

3. 部署问题：

   • 确保 WAR 文件包含所有必要资源
   • 检查运行时依赖是否完整
   • 对于 Spring Boot，确保正确配置了主类

8. 最佳实践

1. 保持 build.gradle 简洁，复杂逻辑封装到自定义插件中
2. 使用 Gradle Wrapper 确保构建一致性
3. 为不同环境创建单独的构建配置
4. 定期清理不再使用的依赖
5. 使用 --scan 选项分析构建性能

---

Android 项目构建示例

Gradle 构建脚本基础

在 Android 项目中，Gradle 构建脚本通常由以下几个部分组成：

1. 项目级 build.gradle：位于项目根目录，配置所有模块共用的构建逻辑。

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "com.android.tools.build:gradle:7.0.4"
    }
}

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

2. 模块级 build.gradle：位于每个模块目录（如 app/），配置特定模块的构建选项。

plugins {
    id 'com.android.application'
}

android {
    compileSdkVersion 31

    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 21
        targetSdkVersion 31
        versionCode 1
        versionName "1.0"
    }

    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

dependencies {
    implementation 'androidx.appcompat:appcompat:1.4.0'
    implementation 'com.google.android.material:material:1.4.0'
}

常见构建任务

Gradle 为 Android 项目提供了标准构建任务：

1. 基础任务：

# 清理构建产物
./gradlew clean

# 构建所有变体
./gradlew build

# 安装调试版到设备
./gradlew installDebug

2. 变体构建（针对不同构建类型和产品风味）：

# 构建特定变体（如 release 版本）
./gradlew assembleRelease

# 构建特定产品风味的 debug 版本
./gradlew assembleFreeDebug

多模块项目配置

对于包含多个模块的项目（如 app, library），需要在 settings.gradle 中声明：

include ':app', ':library'

模块间依赖通过 dependencies 配置：

// 在 app 模块中引用 library 模块
implementation project(':library')

自定义构建配置

1. 构建类型扩展：

android {
    buildTypes {
        staging {
            initWith debug
            manifestPlaceholders = [hostName:"stage.example.com"]
        }
    }
}

2. 产品风味配置：

android {
    flavorDimensions "version"
    productFlavors {
        free {
            dimension "version"
            applicationIdSuffix ".free"
        }
        paid {
            dimension "version"
            applicationIdSuffix ".paid"
        }
    }
}

3. 自定义构建逻辑：

android.applicationVariants.all { variant ->
    variant.outputs.all {
        outputFileName = "app-${variant.name}-${variant.versionName}.apk"
    }
}

注意事项

1. Gradle 版本兼容性：

   • 确保 gradle-wrapper.properties 中的 Gradle 版本与 Android Gradle 插件版本兼容
   • 参考官方兼容性表格：https://developer.android.com/studio/releases/gradle-plugin

2. 构建性能优化：

   • 启用构建缓存：org.gradle.caching=true
   • 配置守护进程：org.gradle.daemon=true
   • 使用最新版构建工具

3. 依赖管理最佳实践：

   • 避免动态版本号（如 1.+）
   • 使用 implementation 而非 compile（已废弃）
   • 定期执行 ./gradlew dependencyUpdates 检查依赖更新

4. 常见问题处理：

   • 清理缓存：./gradlew cleanBuildCache
   • 查看依赖树：./gradlew dependencies
   • 调试构建：./gradlew --stacktrace --info

---

多模块项目构建示例

什么是多模块项目构建

多模块项目构建是指将一个大型项目拆分成多个相互关联的子模块（Module），每个子模块可以独立编译、测试和打包，同时又能作为一个整体进行构建。Gradle 通过 settings.gradle 和 build.gradle 文件来管理多模块项目的依赖关系和构建逻辑。

多模块项目的优势

1. 代码复用：公共代码可以抽离到独立的模块，供其他模块依赖。
2. 职责分离：不同模块可以专注于特定功能（如核心逻辑、Web 层、数据访问层等）。
3. 构建效率：Gradle 支持增量编译，仅重新构建发生变化的模块。
4. 依赖管理：可以清晰定义模块间的依赖关系，避免循环依赖。

多模块项目结构示例

以下是一个典型的多模块项目目录结构：

my-multi-module-project/
├── settings.gradle                  # 定义包含哪些子模块
├── build.gradle                     # 根项目的构建配置
├── module-core/                     # 核心模块
│   ├── build.gradle
│   └── src/
├── module-web/                      # Web 模块
│   ├── build.gradle
│   └── src/
└── module-data/                     # 数据访问模块
    ├── build.gradle
    └── src/

关键配置文件示例

1. settings.gradle

rootProject.name = 'my-multi-module-project'  // 根项目名称

// 包含的子模块
include 'module-core'
include 'module-web'
include 'module-data'

2. 根项目的 build.gradle

// 公共配置（所有子模块共享）
subprojects {
    apply plugin: 'java'
    apply plugin: 'maven-publish'

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

    repositories {
        mavenCentral()
    }

    dependencies {
        testImplementation 'junit:junit:4.13.2'
    }
}

// 单独配置某个子模块
project(':module-web') {
    dependencies {
        implementation project(':module-core')  // 依赖 core 模块
    }
}

3. 子模块的 build.gradle（以 module-data 为例）

dependencies {
    implementation project(':module-core')  // 依赖 core 模块
    implementation 'org.hibernate:hibernate-core:5.6.0.Final'
}

常见依赖关系配置

1. implementation：当前模块私有依赖，不会泄露给依赖该模块的其他模块。

   implementation project(':module-core')
   

2. api：依赖会传递给其他依赖该模块的模块（类似 Maven 的 compile）。

   api project(':module-common')
   

3. testImplementation：仅用于测试的依赖。

   testImplementation 'org.mockito:mockito-core:3.12.4'
   

构建与测试

1. 构建所有模块：

   gradle build
   

2. 构建单个模块：

   gradle :module-core:build
   

3. 查看依赖树：

   gradle dependencies
   

注意事项

1. 避免循环依赖：模块 A 依赖模块 B，模块 B 又依赖模块 A 会导致构建失败。
2. 统一版本管理：推荐在根项目的 build.gradle 中使用 ext 定义公共版本号：

   ext {
       springBootVersion = '2.7.0'
   }
   

   子模块中引用：

   implementation "org.springframework.boot:spring-boot-starter:$springBootVersion"
   

3. 性能优化：对频繁变动的模块使用 compileOnly 或 runtimeOnly 减少重新编译范围。

高级技巧：复合构建（Composite Builds）

当需要集成外部独立项目时：

// settings.gradle
includeBuild '../external-library'

然后在依赖中直接引用：

implementation 'com.external:library:1.0'

---