第29章迁移与升级

课程目录第29章迁移与升级

第29章：迁移与升级：从Maven迁移、从Ant迁移、Gradle版本升级、兼容性处理

说实话，做Java项目这么多年，我见过太多团队卡在构建工具迁移这一步。明明知道Gradle好，就是不敢动。为什么？怕出问题，怕影响交付。今天我就把这块硬骨头啃下来，聊聊怎么从Maven和Ant迁移到Gradle，以及版本升级的那些坑。

一、从Maven迁移到Gradle

Maven用户转Gradle，其实没那么可怕。我当年带团队迁移一个20+模块的老项目，前后只花了两天。关键是要摸清对应关系。

1.1 核心概念对照

Maven概念	Gradle对应	说明
pom.xml	build.gradle	构建配置文件
groupId:artifactId:version	group:name:version	坐标定义，基本一致
dependencies	dependencies {} 块	依赖声明
plugins	plugins {} 块	插件配置
profiles	build variants / 条件配置	多环境构建

1.2 自动迁移工具

Gradle官方提供了一个叫 gradle init 的命令，能自动把Maven项目转成Gradle项目。我个人习惯先用它跑一遍，再手动调整。

# 在Maven项目根目录执行
gradle init --type pom

# 或者指定转换类型
gradle init --type pom --dsl groovy

这个命令会读取pom.xml，自动生成build.gradle和settings.gradle。我在项目中遇到过一个问题：如果pom里有复杂的profile配置，自动转换可能不完整。这时候就需要手动补一下。

1.3 手动迁移要点

如果你决定手动迁移，记住这几个关键点：

依赖管理：Maven的<dependencyManagement>对应Gradle的dependencyManagement（需要io.spring.dependency-management插件）或直接使用platform()
多模块：Maven的<modules>对应settings.gradle中的include语句
资源过滤：Maven的<filters>对应Gradle的processResources任务配置

避坑指南：我曾经把一个Maven项目直接复制粘贴依赖到Gradle里，结果发现scope对应关系搞错了。Maven的provided对应Gradle的compileOnly，runtime对应runtimeOnly，别搞混了。

二、从Ant迁移到Gradle

Ant迁移比Maven麻烦一些。为什么？因为Ant太灵活了，没有固定约定。我见过有的Ant项目，build.xml写了上千行，全是自定义任务。

2.1 理解Ant的构建逻辑

Ant的核心是target和task。每个target可以依赖其他target，task执行具体操作。Gradle里，target对应task，依赖关系用dependsOn声明。

// Ant风格的target
<target name="compile" depends="init">
    <javac srcdir="src" destdir="build"/>
</target>

// Gradle等价写法
task compile(dependsOn: 'init') {
    doLast {
        ant.javac(srcdir: 'src', destdir: 'build')
    }
}

你想想看，Gradle其实可以直接调用Ant的task。这意味着你可以逐步迁移，不用一次性全改完。

2.2 渐进式迁移策略

我个人推荐三步走：

保留Ant，引入Gradle：在build.gradle里用ant.importBuild 'build.xml'直接导入Ant脚本
逐个替换：把Ant的target逐步改写成Gradle的task，每次只改一个
完全替换：当所有Ant target都被替换后，删除build.xml

小技巧：Ant的<path>元素对应Gradle的configurations。如果你在Ant里定义了classpath，可以在Gradle里用configurations { antClasspath }来管理。

三、Gradle版本升级

Gradle版本升级，说白了就是换一个wrapper版本。但这里面的坑，我踩过不少。

3.1 升级步骤

# 查看当前版本
gradle --version

# 修改gradle-wrapper.properties
# distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip

# 或者直接运行
gradle wrapper --gradle-version 8.5

嗯，这里要注意：升级后一定要跑一遍gradle clean build，看看有没有废弃API的警告。

3.2 版本兼容性矩阵

Gradle版本	最低Java版本	主要变化
7.x	Java 8	配置缓存稳定、生命周期API调整
8.x	Java 17	废弃了部分API、构建速度优化
9.x（预览）	Java 21	更严格的配置隔离

警告：从Gradle 7升级到8时，compile和runtime配置被彻底移除。如果你还在用它们，升级前必须改成implementation和api。我曾经有个项目没注意这个，升级后编译直接挂了。

四、兼容性处理

兼容性处理，说白了就是让新旧版本和平共处。我总结了几条实战经验：

4.1 插件兼容性

Gradle插件通常绑定特定版本范围。升级Gradle时，先检查插件是否支持新版本。

// 在build.gradle中声明插件版本范围
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.0' apply false
}

// 或者使用Gradle版本目录
// libs.versions.toml
[versions]
gradle = "8.5"
spring-boot = "3.2.0"

[libraries]
spring-boot-gradle-plugin = { module = "org.springframework.boot:spring-boot-gradle-plugin", version.ref = "spring-boot" }

4.2 API废弃处理

Gradle每个大版本都会废弃一批API。升级时，我建议开启废弃警告：

// gradle.properties
org.gradle.warning.mode=all

// 或者在命令行
gradle build --warning-mode all

这样能提前看到哪些API即将被移除。我曾经靠这个方式，在升级前就把所有废弃API都替换掉了，升级过程异常顺利。

4.3 多版本兼容方案

如果你的项目需要同时支持多个Gradle版本，可以用条件判断：

if (GradleVersion.current() >= GradleVersion.version('8.0')) {
    // 使用新API
    tasks.named('compileJava') {
        options.release = 17
    }
} else {
    // 使用旧API
    tasks.withType(JavaCompile) {
        sourceCompatibility = '17'
        targetCompatibility = '17'
    }
}

核心原则：迁移和升级不是一锤子买卖。我建议每次只做一件事：要么从Maven迁移到Gradle，要么升级Gradle版本。两件事一起做，出了问题你都不知道是哪个环节导致的。

五、知识体系总览

下面这张图，是我对本章内容的总结。你可以把它当作迁移升级的路线图。

迁移和升级这件事，说白了就是「胆大心细」。工具是死的，人是活的。只要掌握了核心对应关系，再复杂的项目也能平稳过渡。记住我前面说的：一次只做一件事，出了问题好排查。

好了，这一章的内容就到这里。希望这些实战经验能帮你少走弯路。

📚 课程目录