从 Maven 迁移到 Gradle

自动迁移工具

Gradle 提供了自动迁移命令，可将 Maven 项目转换为 Gradle 项目：

# 在 Maven 项目根目录执行
gradle init

# 选择：
# 2: application 或 3: library
# 然后选择：Keep existing build（保留现有 Maven 配置并生成 Gradle 文件）

或者使用迁移子命令：

gradle init --type pom

这会读取 pom.xml 并生成对应的 build.gradle.kts 和 settings.gradle.kts。

概念对照

Maven 概念	Gradle 对应	说明
pom.xml	build.gradle.kts	构建脚本
settings.xml（用户）	~/.gradle/gradle.properties	全局配置
pom.xml <modules>	settings.gradle.kts include()	多模块声明
groupId	group	项目组
artifactId	archivesName / 项目名	产物名称
version	version	项目版本
Phase（阶段）	Task（任务）	构建步骤
Plugin Goal	Task Action	具体操作
~/.m2/repository	~/.gradle/caches	本地缓存

依赖 Scope 对照

Maven scope	Gradle configuration	说明
compile（默认）	implementation	编译+运行时
provided	compileOnly	仅编译
runtime	runtimeOnly	仅运行时
test	testImplementation	测试
compile（推荐用于库）	api	传递给消费者
import（BOM）	platform()	BOM 导入
system	files()	本地文件

pom.xml → build.gradle.kts 转换示例

项目基本信息

<!-- Maven pom.xml -->
<groupId>com.example</groupId>
<artifactId>my-app</artifactId>
<version>1.0.0</version>
<packaging>jar</packaging>

// Gradle build.gradle.kts
group = "com.example"
version = "1.0.0"
// packaging 由插件决定（java → jar，war → war）

属性

<!-- Maven -->
<properties>
    <java.version>17</java.version>
    <spring-boot.version>3.2.0</spring-boot.version>
    <maven.compiler.source>${java.version}</maven.compiler.source>
    <maven.compiler.target>${java.version}</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

// Gradle
java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}
tasks.withType<JavaCompile> {
    options.encoding = "UTF-8"
}
// 版本用版本目录管理：gradle/libs.versions.toml

依赖

<!-- Maven -->
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

// Gradle
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    compileOnly("org.projectlombok:lombok")
    annotationProcessor("org.projectlombok:lombok")
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.1")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

BOM 导入

<!-- Maven -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.2.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

// Gradle
dependencies {
    implementation(platform("org.springframework.boot:spring-boot-dependencies:3.2.0"))
}

插件

<!-- Maven -->
<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <source>17</source>
                <target>17</target>
            </configuration>
        </plugin>
    </plugins>
</build>

// Gradle
plugins {
    id("org.springframework.boot") version "3.2.0"
    // maven-compiler-plugin 的功能由 java 插件内置处理
}

多模块

<!-- Maven 父 pom.xml -->
<modules>
    <module>core</module>
    <module>web</module>
    <module>service</module>
</modules>

// Gradle settings.gradle.kts
include("core", "web", "service")

排除依赖

<!-- Maven -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>

// Gradle
implementation("org.springframework.boot:spring-boot-starter-web") {
    exclude(group = "org.springframework.boot", module = "spring-boot-starter-tomcat")
}

生命周期命令对照

Maven 命令	Gradle 命令	说明
mvn compile	./gradlew compileJava	编译
mvn test	./gradlew test	测试
mvn package	./gradlew jar / ./gradlew build	打包
mvn verify	./gradlew check	验证
mvn install	./gradlew publishToMavenLocal	安装到本地
mvn deploy	./gradlew publish	发布
mvn clean	./gradlew clean	清理
mvn clean package	./gradlew clean build	清理并构建
mvn -DskipTests package	./gradlew build -x test	跳过测试
mvn dependency:tree	./gradlew dependencies	查看依赖树

迁移注意事项

1. Gradle 构建脚本是代码：build.gradle.kts 是真正的 Kotlin 代码，可以使用变量、循环、条件判断

2. 任务比阶段更灵活：Maven 的固定阶段 → Gradle 的任意任务图（DAG）

3. 配置阶段与执行阶段分开：不要在配置阶段做耗时操作

4. 使用 Wrapper：生成 gradlew 文件后提交到版本控制

5. 版本目录替代属性：用 gradle/libs.versions.toml 管理版本，比 Maven 的 <properties> 更清晰

推荐迁移步骤

1. 运行 gradle init --type pom 生成基础文件
2. 检查生成的 build.gradle.kts，手动修正自动迁移的问题
3. 运行 ./gradlew build 验证构建
4. 将版本号迁移到 gradle/libs.versions.toml
5. 配置 镜像加速
6. 启用性能优化选项（缓存、并行）
7. 更新 CI 脚本从 mvn 改为 ./gradlew