Gradle 配置教程：与 Maven 对比详解（含完整迁移指南）

一、基础对比：Gradle vs Maven

1.1 核心特性对比

维度	Maven	Gradle
配置语言	XML (冗长)	Groovy/Kotlin DSL (简洁灵活)
构建速度	较慢(全量构建)	快2-10倍(增量构建+缓存)
多模块管理	<modules> + <parent>	settings.gradle + project()
依赖管理	<dependencies>	dependencies { ... }
插件系统	声明式	编程式(可自定义逻辑)
学习曲线	低(XML基础)	中(需Groovy/Kotlin基础)

1.2 安装与配置对比

Maven 安装流程

wget https://dlcdn.apache.org/maven/maven-3/3.9.6/binaries/apache-maven-3.9.6-bin.zip
unzip apache-maven-3.9.6-bin.zip
export MAVEN_HOME=/path/to/apache-maven-3.9.6
export PATH=$MAVEN_HOME/bin:$PATH
mvn -v  # 验证安装

Gradle 安装优势

wget https://services.gradle.org/distributions/gradle-8.5-bin.zip
unzip gradle-8.5-bin.zip
export GRADLE_HOME=/path/to/gradle-8.5
export PATH=$GRADLE_HOME/bin:$PATH
gradle -v  # 验证安装

​​Gradle优势：​​

• 守护进程(Daemon)减少JVM启动时间
• 支持Gradle Wrapper(无需全局安装)
• Kotlin DSL提供类型安全

1.3 项目结构对比

Maven 标准结构

my-project/
├── pom.xml
└── src/├── main/│   ├── java/│   └── resources/└── test/├── java/└── resources/

Gradle 标准结构

my-project/
├── build.gradle
├── settings.gradle
└── src/├── main/│   ├── java/│   └── resources/└── test/├── java/└── resources/

​​关键差异：​​

• settings.gradle管理多模块和项目名称
• 构建逻辑在build.gradle而非pom.xml

1.4 构建脚本深度对比

Maven 配置示例

<!-- pom.xml -->
<project><modelVersion>4.0.0</modelVersion><groupId>com.example</groupId><artifactId>my-app</artifactId><version>1.0.0</version><properties><java.version>11</java.version></properties><dependencies><dependency><groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter</artifactId><version>5.9.3</version><scope>test</scope></dependency></dependencies><build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.11.0</version><configuration><source>${java.version}</source><target>${java.version}</target></configuration></plugin></plugins></build>
</project>

Gradle 等效配置

// build.gradle (Groovy DSL)
plugins {id 'java'id 'org.jetbrains.kotlin.jvm' version '1.9.22' // 可选Kotlin支持
}group = 'com.example'
version = '1.0.0'repositories {mavenCentral()
}java {toolchain {languageVersion = JavaLanguageVersion.of(11)}
}dependencies {testImplementation 'org.junit.jupiter:junit-jupiter:5.9.3'// Kotlin示例: implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8"
}tasks.withType(Test) {useJUnitPlatform()
}

1.5 多模块项目配置

Maven 多模块配置

<!-- 父pom.xml -->
<modules><module>core</module><module>web</module>
</modules><!-- 子模块pom.xml -->
<parent><groupId>com.example</groupId><artifactId>parent</artifactId><version>1.0.0</version>
</parent>

Gradle 多模块配置

// settings.gradle
rootProject.name = 'my-app'
include 'core', 'web'// web/build.gradle
dependencies {implementation project(':core')// 可添加外部依赖implementation 'org.springframework.boot:spring-boot-starter-web:3.1.5'
}

1.6 构建任务对比

任务	Maven 命令	Gradle 命令
编译	mvn compile	gradle classes
运行测试	mvn test	gradle test
打包	mvn package	gradle assemble
安装到本地	mvn install	gradle publishToMavenLocal
生成网页	mvn site	gradle javadoc
清理	mvn clean	gradle clean
依赖分析	mvn dependency:tree	gradle dependencies
运行应用	mvn exec:java	gradle run

1.7 性能优化对比

优化技术	Maven实现	Gradle实现
增量构建	基于时间戳	基于内容哈希
并行构建	<maven.compile.parallel>true</maven.compile.parallel>	org.gradle.parallel=true (gradle.properties)
构建缓存	无内置支持	本地+远程缓存
任务依赖优化	手动配置	自动分析任务依赖关系
守护进程	无	Gradle Daemon

二、Maven 快速转 Gradle 迁移指南

2.1 自动转换工具

gradle init --type pom

​​交互式配置：​​

Select build script DSL:1: Groovy2: Kotlin
> 2  # 推荐选择Kotlin DSLGenerate build using new APIs and behavior (some may be incompatible with existing scripts)?
> yes

​​生成文件结构：​​

.
├── build.gradle.kts       # 主构建脚本
├── settings.gradle.kts    # 项目配置
├── gradlew                # Unix构建脚本
├── gradlew.bat            # Windows构建脚本
└── gradle/                # Gradle包装器

2.2 手动调整关键配置

依赖作用域映射表

Maven 作用域	Gradle 配置	特殊说明
compile	implementation	默认转换结果
test	testImplementation	自动转换
provided	compileOnly	需手动检查Web容器依赖
runtime	runtimeOnly	需确认是否真的需要
system	❌ 不支持	建议改用文件依赖或Maven仓库

​​修正示例：​​

dependencies {// 修正Servlet API依赖compileOnly("javax.servlet:javax.servlet-api:4.0.1")// 文件依赖示例implementation(files("lib/custom-lib.jar"))
}

2.3 插件转换对照表

Maven 插件	Gradle 等效配置
maven-compiler-plugin	内置Java插件，配置java.toolchain
spring-boot-maven-plugin	添加org.springframework.boot插件
maven-surefire-plugin	内置测试支持
maven-jar-plugin	使用jar任务配置
maven-assembly-plugin	使用DistributionPlugin

​​Spring Boot项目配置：​​

plugins {id("org.springframework.boot") version "3.1.5"id("io.spring.dependency-management") version "1.1.3"
}tasks.named<BootJar>("bootJar") {archiveBaseName = "my-app"archiveVersion = "1.0.0"
}

2.4 多模块项目配置

​​根项目配置 (settings.gradle.kts):​​

rootProject.name = "parent.project"
include("module-core","module-web","module-service:submodule-a",  // 支持嵌套模块"module-service:submodule-b"
)

​​子模块依赖配置:​​

// module-web/build.gradle.kts
dependencies {implementation(project(":core"))implementation("com.google.guava:guava:32.1.3-jre")
}

三、性能优化方案

3.1 构建加速配置

// 启用配置缓存（Gradle 8.0+）
tasks.withType<ConfigurationCache> {mode = ConfigurationCache.Mode.REMOTE
}// 分布式缓存配置
buildCache {remote<HttpBuildCache> {url = uri("https://cache.internal")credentials {username = "cache-user"password = "secret"}}
}

3.2 常见问题解决方案

问题类型	解决方案
依赖冲突	configurations.all { resolutionStrategy.force("com.google.guava:guava:32.1.3-jre") }
构建速度慢	启用 --parallel + 配置 org.gradle.workers.max=8
测试失败缓存	test { outputs.upToDateWhen { false } }
资源处理异常	添加 processResources { duplicatesStrategy = DuplicatesStrategy.INCLUDE }

四、验证与调试

4.1 构建验证流程

# 清洁构建
./gradlew clean build# 测试验证
./gradlew test --info       # 显示测试日志
./gradlew test --continue   # 继续执行失败后的测试# 产物检查
unzip -l build/libs/my-app.jar  # 检查JAR内容
jar tf build/libs/my-app.war    # 检查WAR内容

4.2 依赖分析工具

# 生成依赖树
./gradlew :module-name:dependencies > deps.txt# 可视化依赖报告
./gradlew htmlDependencyReport  # 生成HTML报告# 依赖冲突检测
./gradlew dependencyInsight --dependency guava --configuration runtimeClasspath

4.3 构建扫描分析

./gradlew build --scan

​​关键指标检查：​​

• 任务执行时间分布
• 依赖下载时间
• 缓存命中率
• 配置时间占比

五、迁移后优化建议

5.1 构建脚本重构

// settings.gradle.kts
dependencyResolutionManagement {repositories {mavenCentral()google()maven { url = uri("https://plugins.gradle.org/m2/") }}
}

5.2 CI/CD 集成示例

# .github/workflows/build.yml
jobs:build:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- name: Setup JDKuses: actions/setup-java@v3with:java-version: '17'- name: Gradle Buildrun: ./gradlew build --scanenv:GRADLE_OPTS: "-Dorg.gradle.caching=true"

5.3 监控仪表盘配置

./gradlew build --scan --metrics
# 生成包含以下指标的报告：
# - 任务执行时间分布
# - 依赖下载耗时
# - 内存使用峰值
# - 配置时间占比