1. 从Gradle到Maven一个老项目的转型之路最近在整理一个几年前用Gradle构建的遗留项目准备将其迁移到公司统一的技术栈——Maven上。这听起来像是个简单的格式转换但真正动手时才发现从build.gradle到pom.xml的转变远不止是语法层面的替换。它涉及到依赖管理的哲学差异、插件生态的适配、构建生命周期的重新理解以及团队协作习惯的调整。如果你也正面临类似的迁移需求无论是为了统一构建工具、简化CI/CD流程还是因为某些依赖在Maven仓库中更稳定这篇基于我实际踩坑经验的图文详解或许能帮你避开不少弯路。整个过程我会以一个典型的Spring Boot Web项目为例带你一步步走完转换、验证和优化的全过程。2. 转换前的核心准备理解差异与清理环境在动手修改任何一行代码之前充分的准备是成功迁移的一半。这个阶段的目标不是执行转换而是为转换创造一个干净、可回溯的起点。2.1 剖析Gradle与Maven的核心差异很多人把转换想得太简单以为找个工具自动生成pom.xml就完事了。但如果不理解底层差异生成的配置文件很可能无法工作或者埋下隐患。首先依赖声明的粒度不同。Gradle的依赖配置implementation,api,compileOnly,runtimeOnly等非常精细旨在优化编译类路径和运行时类路径这对构建性能有帮助。而Maven主要依赖scope来管理常见的有compile默认、provided、runtime、test。在转换时你需要进行映射Gradle的implementation- Maven的compilescope最常用。compileOnly-providedscope依赖仅用于编译不会打包。runtimeOnly-runtimescope仅用于运行时编译时不需要。testImplementation-testscope。其次多模块项目的结构迥异。Gradle的多模块通过在settings.gradle中include子项目并在子项目的build.gradle中通过dependencies { implementation project(‘:module-a’) }来声明模块依赖。Maven则通过父pom.xml中的modules标签聚合子模块子模块通过parent标签继承父POM模块间依赖使用普通的dependency声明但groupId和artifactId指向兄弟模块。这个结构转换需要手动调整目录和POM文件。再者插件和自定义任务。Gradle的插件应用apply plugin: ‘java’和自定义Tasktask customTask { … }是其强大灵活性的体现。Maven没有直接对应的“任务”概念其功能主要通过插件plugins及其目标goals来实现。复杂的Gradle自定义任务可能需要用Maven插件重写或者借助maven-antrun-plugin执行一些Shell/命令但这往往是迁移中最棘手的部分。注意对于简单的项目自动转换工具可以处理基础依赖。但对于使用了复杂Gradle插件如特定版本的Android插件、ShadowJar打包插件或大量自定义构建逻辑的项目自动转换基本会失败必须手动分析和重写。2.2 为当前Gradle项目创建“快照”在开始转换前务必确保你的Gradle项目处于一个“干净”且可构建的状态。这为你提供了回滚基准和对照验证的源头。清理并构建在项目根目录下执行./gradlew clean buildWindows下为gradlew.bat clean build。确保构建成功没有测试失败除非是预期内的。这验证了项目当前是健康的。生成依赖报告使用Gradle命令生成依赖树这对于后续核对Maven依赖版本至关重要。./gradlew dependencies gradle_dependencies.txt ./gradlew dependencies --configuration runtimeClasspath gradle_runtime_dependencies.txt第一个命令生成所有配置的依赖信息量巨大。第二个命令生成运行时类路径的依赖这通常是你最终打包进应用jar/war的依赖集合是转换核对的重点。备份关键文件除了整个项目代码使用Git备份确保已提交所有更改外建议单独复制出关键的Gradle配置文件build.gradle(或build.gradle.kts)settings.gradlegradle.propertiesgradle/wrapper/gradle-wrapper.properties记录了Gradle版本这个“快照”能让你在转换过程中迷茫时随时回头查看Gradle原本是如何做的。3. 执行转换从build.gradle到pom.xml这是迁移的核心操作阶段。我们将采用“工具辅助生成 人工校对优化”的策略而不是完全手动编写POM。3.1 使用gradle init进行基础转换从Gradle 6.0开始gradle init命令支持将现有项目转换为Maven项目。这是最官方的起点。在项目根目录打开终端或命令行。执行转换命令./gradlew init --type pom或者如果你系统安装了全局Gradlegradle init --type pom命令执行后Gradle会在当前目录生成一个基本的pom.xml文件。重要提示这个命令不会删除你原有的Gradle文件它只是新增了一个POM文件。然而根据我的经验这个自动生成的pom.xml通常非常基础它主要做了以下几件事根据项目目录名和gradle.properties中的信息设置groupId,artifactId,version。将build.gradle中声明的依赖尝试转换为Maven的dependency并使用compilescope。设置源码编码为UTF-8。添加maven-compiler-plugin并指定Java版本。它不会处理多模块项目结构。复杂的依赖配置如exclude、force版本、自定义源。任何插件和构建逻辑。资源文件过滤等配置。所以生成的pom.xml只是一个粗糙的毛坯房我们需要把它装修成能住的房子。3.2 手动完善与校对pom.xml打开生成的pom.xml我们开始进行深度加工。下面是一个从Spring Boot Gradle项目转换后初步完善的pom.xml示例?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion !-- 1. 坐标信息根据你的项目修改 -- groupIdcom.example/groupId artifactIdmy-springboot-app/artifactId version1.0.0-SNAPSHOT/version packagingjar/packaging !-- 如果是web项目可能是war -- !-- 2. 父POM对于Spring Boot项目继承官方starter-parent是最佳实践 -- parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version !-- 请匹配你Gradle项目中的Spring Boot版本 -- relativePath/ !-- 从仓库查找不继承本地 -- /parent properties java.version11/java.version !-- 与Gradle中sourceCompatibility一致 -- project.build.sourceEncodingUTF-8/project.build.sourceEncoding !-- 可以在这里统一管理依赖版本类似于Gradle的ext或version catalog -- lombok.version1.18.30/lombok.version /properties dependencies !-- Spring Boot Starter Web -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId !-- 版本由父POM管理无需指定 -- /dependency !-- Spring Boot Starter Test -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency !-- Lombok -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId version${lombok.version}/version scopeprovided/scope !-- 对应Gradle的compileOnly -- /dependency !-- MySQL Connector -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId !-- 版本可能由Spring Boot管理也可在properties中自定义 -- scoperuntime/scope !-- 对应Gradle的runtimeOnly -- /dependency !-- 其他依赖... -- !-- 仔细核对 gradle_runtime_dependencies.txt 文件逐一添加 -- /dependencies build plugins !-- Spring Boot Maven Plugin用于打包可执行jar -- plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin !-- Maven Compiler Plugin父POM已配置通常无需重复 -- !-- 如果需要特殊配置可以覆盖 -- plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId configuration source${java.version}/source target${java.version}/target encoding${project.build.sourceEncoding}/encoding /configuration /plugin /plugins !-- 资源文件过滤配置如果需要 -- resources resource directorysrc/main/resources/directory filteringtrue/filtering !-- 是否替换资源文件中的占位符 -- includes include**/*.properties/include include**/*.yml/include /includes /resource /resources /build /project校对关键点依赖版本核对这是最容易出错的地方。将生成的pom.xml中的依赖与gradle_dependencies.txt报告逐一对比。重点关注那些没有从父POM继承版本的依赖如Lombok、某些工具类库。确保版本号一致。Maven的依赖传递机制和Gradle不同有时需要显式声明某个传递依赖的版本以避免冲突。Scope映射核对根据2.1节的映射关系检查每个依赖的scope是否正确。特别是provided和runtime弄错会导致编译错误或打包体积过大。插件功能替代在Gradle中java插件自动完成了编译、测试、打包等任务。在Maven中这是由maven-compiler-plugin,maven-surefire-plugin,maven-jar-plugin等完成的。如果你继承了spring-boot-starter-parent这些插件都已预配置好。否则你需要手动添加和配置它们。仓库配置如果Gradle项目配置了阿里云、华为云等镜像仓库你需要在Maven的settings.xml用户全局或项目级或pom.xml的repositories中配置对应的镜像以加速依赖下载。4. 构建验证与常见问题排错生成并完善pom.xml后绝不能假设迁移已经成功。必须通过严格的构建和测试来验证。4.1 执行Maven构建生命周期在包含pom.xml的根目录下打开新的终端避免Gradle环境变量干扰执行标准构建命令mvn clean compile此命令清理旧编译结果并编译主代码。这是第一道关卡可以检查编译时依赖compilescope是否齐全语法是否兼容。mvn clean test此命令编译并运行所有测试。这是验证迁移是否成功的黄金标准。如果所有测试通过说明代码的核心功能在Maven环境下运行正常。测试依赖testscope是否正确配置也在此环节验证。mvn clean package此命令执行完整构建并打包生成target/*.jar或target/*.war。这会验证运行时依赖runtimescope和打包插件如spring-boot-maven-plugin的配置是否正确。4.2 典型问题与解决方案在验证过程中你几乎一定会遇到一些问题。以下是几个高频问题及其排查思路问题一依赖找不到Could not resolve dependencies现象mvn compile失败提示某个artifactId或version在仓库中不存在。排查检查pom.xml中该依赖的groupId,artifactId,version是否拼写正确。去 Maven中央仓库 或你配置的镜像仓库网页搜索该坐标确认是否存在。特别关注版本号。Gradle有时可以使用表示动态版本或者通过platform/BOM管理版本。Maven中需要固定具体的版本号或者通过dependencyManagement导入BOM。检查是否需要添加特定的repository比如有些公司私有库或Spring Milestone仓库。问题二类找不到ClassNotFoundException或NoClassDefFoundError现象编译成功但运行测试或启动应用时抛类找不到异常。排查Scope错误最可能的原因。一个在Gradle中是implementation的依赖在Maven中被错误地声明为provided或test。回顾2.1节的映射修正scope。依赖缺失某个必要的传递依赖在Maven的依赖树中没有被引入。使用mvn dependency:tree命令查看完整的依赖树与Gradle的dependencies输出对比找到缺失的依赖并显式声明。包路径冲突罕见的包名/类名冲突。使用mvn dependency:tree -Dverbose查看冲突并用exclusions排除不需要的传递依赖。问题三测试失败现象mvn test失败但之前gradle test是成功的。排查测试依赖确认所有测试专用的依赖如JUnit 5的junit-jupiter-api,junit-jupiter-engineMockito等都已正确添加且scope为test。测试资源Gradle的src/test/resources目录默认会被加入测试类路径。Maven同样如此。但如果你的测试代码动态读取资源文件注意路径差异。可以使用getClass().getResource(/file.txt)来获取。系统属性或环境变量有些测试可能依赖通过Gradletest任务设置的JVM系统属性。在Maven中需要在maven-surefire-plugin配置中设置plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-surefire-plugin/artifactId configuration systemPropertyVariables your.property.keyproperty-value/your.property.key /systemPropertyVariables /configuration /plugin问题四打包结果不正确现象mvn package生成的jar/war文件无法运行或缺少资源文件。排查可执行Jar对于Spring Boot项目必须使用spring-boot-maven-plugin否则打出来的jar没有内嵌容器和主类信息。确保该插件已配置。资源文件遗漏检查buildresources配置。默认情况下src/main/resources下的文件会被复制到target/classes并打包。如果你的资源文件在非标准位置需要在这里额外配置resource。主类清单非Spring Boot的普通可执行Jar需要在maven-jar-plugin中配置archive和manifest来指定主类。5. 多模块项目的迁移策略单模块项目的迁移相对直接。对于多模块项目迁移需要更系统的规划。核心思想是先建立Maven的父子项目结构再逐个模块迁移。5.1 建立Maven项目结构假设原Gradle项目结构如下my-multi-module-project/ ├── build.gradle ├── settings.gradle ├── module-api/ │ └── build.gradle ├── module-service/ │ └── build.gradle └── module-web/ └── build.gradle目标Maven结构my-multi-module-project/ ├── pom.xml (父POM打包类型为pom) ├── module-api/ │ ├── pom.xml │ └── src/ ├── module-service/ │ ├── pom.xml │ └── src/ └── module-web/ ├── pom.xml └── src/创建父POM在项目根目录创建pom.xml其packaging为pom并在modules中列出所有子模块。!-- 根目录 pom.xml -- project ... modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdmy-multi-module-parent/artifactId version1.0.0-SNAPSHOT/version packagingpom/packaging !-- 关键 -- modules modulemodule-api/module modulemodule-service/module modulemodule-web/module /modules !-- 在父POM中定义公共依赖管理和属性 -- dependencyManagement dependencies !-- 统一管理各子模块共用依赖的版本 -- /dependencies /dependencyManagement properties !-- 公共属性 -- /properties /project迁移子模块进入每个子模块目录如module-api使用gradle init --type pom为该模块生成独立的pom.xml。然后手动编辑这个子pom.xml添加parent指向根项目的坐标。移除父POM中已定义的公共依赖的version。将Gradle中implementation project(‘:module-api’)的依赖转换为Maven中对兄弟模块的普通依赖声明使用在子模块POM中定义的groupId和artifactId。5.2 处理模块间依赖这是多模块迁移的关键。在子模块module-service的pom.xml中如果需要依赖module-api应该这样声明!-- module-service/pom.xml -- project ... parent groupIdcom.example/groupId artifactIdmy-multi-module-parent/artifactId version1.0.0-SNAPSHOT/version /parent artifactIdmodule-service/artifactId dependencies dependency !-- 依赖兄弟模块 -- groupIdcom.example/groupId artifactIdmodule-api/artifactId version${project.version}/version !-- 版本通常与父项目一致 -- /dependency !-- 其他外部依赖 -- /dependencies /project重要提示在Maven中构建顺序由模块依赖关系自动决定。你需要先在根目录执行mvn clean install将子模块安装到本地仓库这样其他模块才能引用到。或者始终在根目录执行mvn clean compile/packageMaven会按正确顺序构建所有模块。6. 迁移后的优化与收尾工作当所有模块都能通过mvn clean test和mvn clean package后迁移的主要技术工作就完成了。但为了让项目更健壮、更符合Maven生态的最佳实践还需要做一些优化和收尾。6.1 利用Maven特性优化配置依赖管理Dependency Management在父POM中使用dependencyManagement统一管理所有子模块共用的依赖版本。这能极大避免版本冲突类似于Gradle的platform或版本目录Version Catalog。dependencyManagement dependencies dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId version${lombok.version}/version /dependency !-- 其他通用依赖 -- /dependencies /dependencyManagement子模块中引用这些依赖时可以省略version标签。插件管理Plugin Management同样在父POM中使用pluginManagement统一配置各模块共用的插件版本和配置确保构建行为一致。资源过滤与ProfileMaven的资源过滤filteringtrue/filtering功能强大可以结合profiles为不同环境dev, test, prod打包不同的配置文件。这是Gradle需要额外插件才能方便实现的功能现在可以原生用起来。6.2 清理与文档更新移除Gradle文件确认Maven构建完全稳定后可以安全删除Gradle相关的文件了build.gradle,settings.gradle,gradle.propertiesgradle/目录gradlew,gradlew.bat项目中的.gradle缓存目录通常可以忽略谨慎操作建议先使用Git等版本控制系统提交Maven化后的稳定代码然后再删除这些文件。或者先将它们移动到一个备份目录。更新IDE项目文件如果你使用IntelliJ IDEA或Eclipse需要重新导入项目。IntelliJ IDEA关闭项目。删除项目根目录下的.idea目录和所有的.iml文件。然后使用File - Open选择包含pom.xml的根目录IDEA会将其识别为Maven项目并重新导入。Eclipse删除项目不从磁盘删除。然后使用File - Import - Maven - Existing Maven Projects重新导入。更新CI/CD流水线将Jenkins、GitLab CI等持续集成脚本中的构建命令从./gradlew build改为mvn clean package。同时检查是否需要更新构建节点上的工具安装从Gradle切换到Maven。更新项目README在项目说明文档中将构建指南从Gradle命令更新为Maven命令。6.3 最后的验证清单在宣布迁移完成前运行一遍这个清单[ ]mvn clean compile成功。[ ]mvn clean test成功所有单元测试和集成测试通过。[ ]mvn clean package成功生成的jar/war包在目标环境如测试服务器可正常启动运行。[ ] 多模块项目在根目录执行mvn clean install所有模块按顺序构建成功且模块间依赖正确。[ ] IDE中项目导入正常代码无报错依赖库显示正确运行/调试配置可正常工作。[ ] 团队其他成员能用新的Maven配置成功拉取代码并构建。迁移本身是一次性的但理解两个工具背后的设计理念能让你在未来无论使用哪种工具都更加得心应手。Gradle的灵活和性能与Maven的约定和稳定各有其适用场景。这次转换过程实际上是一次对项目构建生命周期的深度梳理往往能发现并清理掉一些陈旧的、不必要的依赖或配置让项目结构变得更加清晰。
1. 从Gradle到Maven一个老项目的转型之路最近在整理一个几年前用Gradle构建的遗留项目准备将其迁移到公司统一的技术栈——Maven上。这听起来像是个简单的格式转换但真正动手时才发现从build.gradle到pom.xml的转变远不止是语法层面的替换。它涉及到依赖管理的哲学差异、插件生态的适配、构建生命周期的重新理解以及团队协作习惯的调整。如果你也正面临类似的迁移需求无论是为了统一构建工具、简化CI/CD流程还是因为某些依赖在Maven仓库中更稳定这篇基于我实际踩坑经验的图文详解或许能帮你避开不少弯路。整个过程我会以一个典型的Spring Boot Web项目为例带你一步步走完转换、验证和优化的全过程。2. 转换前的核心准备理解差异与清理环境在动手修改任何一行代码之前充分的准备是成功迁移的一半。这个阶段的目标不是执行转换而是为转换创造一个干净、可回溯的起点。2.1 剖析Gradle与Maven的核心差异很多人把转换想得太简单以为找个工具自动生成pom.xml就完事了。但如果不理解底层差异生成的配置文件很可能无法工作或者埋下隐患。首先依赖声明的粒度不同。Gradle的依赖配置implementation,api,compileOnly,runtimeOnly等非常精细旨在优化编译类路径和运行时类路径这对构建性能有帮助。而Maven主要依赖scope来管理常见的有compile默认、provided、runtime、test。在转换时你需要进行映射Gradle的implementation- Maven的compilescope最常用。compileOnly-providedscope依赖仅用于编译不会打包。runtimeOnly-runtimescope仅用于运行时编译时不需要。testImplementation-testscope。其次多模块项目的结构迥异。Gradle的多模块通过在settings.gradle中include子项目并在子项目的build.gradle中通过dependencies { implementation project(‘:module-a’) }来声明模块依赖。Maven则通过父pom.xml中的modules标签聚合子模块子模块通过parent标签继承父POM模块间依赖使用普通的dependency声明但groupId和artifactId指向兄弟模块。这个结构转换需要手动调整目录和POM文件。再者插件和自定义任务。Gradle的插件应用apply plugin: ‘java’和自定义Tasktask customTask { … }是其强大灵活性的体现。Maven没有直接对应的“任务”概念其功能主要通过插件plugins及其目标goals来实现。复杂的Gradle自定义任务可能需要用Maven插件重写或者借助maven-antrun-plugin执行一些Shell/命令但这往往是迁移中最棘手的部分。注意对于简单的项目自动转换工具可以处理基础依赖。但对于使用了复杂Gradle插件如特定版本的Android插件、ShadowJar打包插件或大量自定义构建逻辑的项目自动转换基本会失败必须手动分析和重写。2.2 为当前Gradle项目创建“快照”在开始转换前务必确保你的Gradle项目处于一个“干净”且可构建的状态。这为你提供了回滚基准和对照验证的源头。清理并构建在项目根目录下执行./gradlew clean buildWindows下为gradlew.bat clean build。确保构建成功没有测试失败除非是预期内的。这验证了项目当前是健康的。生成依赖报告使用Gradle命令生成依赖树这对于后续核对Maven依赖版本至关重要。./gradlew dependencies gradle_dependencies.txt ./gradlew dependencies --configuration runtimeClasspath gradle_runtime_dependencies.txt第一个命令生成所有配置的依赖信息量巨大。第二个命令生成运行时类路径的依赖这通常是你最终打包进应用jar/war的依赖集合是转换核对的重点。备份关键文件除了整个项目代码使用Git备份确保已提交所有更改外建议单独复制出关键的Gradle配置文件build.gradle(或build.gradle.kts)settings.gradlegradle.propertiesgradle/wrapper/gradle-wrapper.properties记录了Gradle版本这个“快照”能让你在转换过程中迷茫时随时回头查看Gradle原本是如何做的。3. 执行转换从build.gradle到pom.xml这是迁移的核心操作阶段。我们将采用“工具辅助生成 人工校对优化”的策略而不是完全手动编写POM。3.1 使用gradle init进行基础转换从Gradle 6.0开始gradle init命令支持将现有项目转换为Maven项目。这是最官方的起点。在项目根目录打开终端或命令行。执行转换命令./gradlew init --type pom或者如果你系统安装了全局Gradlegradle init --type pom命令执行后Gradle会在当前目录生成一个基本的pom.xml文件。重要提示这个命令不会删除你原有的Gradle文件它只是新增了一个POM文件。然而根据我的经验这个自动生成的pom.xml通常非常基础它主要做了以下几件事根据项目目录名和gradle.properties中的信息设置groupId,artifactId,version。将build.gradle中声明的依赖尝试转换为Maven的dependency并使用compilescope。设置源码编码为UTF-8。添加maven-compiler-plugin并指定Java版本。它不会处理多模块项目结构。复杂的依赖配置如exclude、force版本、自定义源。任何插件和构建逻辑。资源文件过滤等配置。所以生成的pom.xml只是一个粗糙的毛坯房我们需要把它装修成能住的房子。3.2 手动完善与校对pom.xml打开生成的pom.xml我们开始进行深度加工。下面是一个从Spring Boot Gradle项目转换后初步完善的pom.xml示例?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion !-- 1. 坐标信息根据你的项目修改 -- groupIdcom.example/groupId artifactIdmy-springboot-app/artifactId version1.0.0-SNAPSHOT/version packagingjar/packaging !-- 如果是web项目可能是war -- !-- 2. 父POM对于Spring Boot项目继承官方starter-parent是最佳实践 -- parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version !-- 请匹配你Gradle项目中的Spring Boot版本 -- relativePath/ !-- 从仓库查找不继承本地 -- /parent properties java.version11/java.version !-- 与Gradle中sourceCompatibility一致 -- project.build.sourceEncodingUTF-8/project.build.sourceEncoding !-- 可以在这里统一管理依赖版本类似于Gradle的ext或version catalog -- lombok.version1.18.30/lombok.version /properties dependencies !-- Spring Boot Starter Web -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId !-- 版本由父POM管理无需指定 -- /dependency !-- Spring Boot Starter Test -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency !-- Lombok -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId version${lombok.version}/version scopeprovided/scope !-- 对应Gradle的compileOnly -- /dependency !-- MySQL Connector -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId !-- 版本可能由Spring Boot管理也可在properties中自定义 -- scoperuntime/scope !-- 对应Gradle的runtimeOnly -- /dependency !-- 其他依赖... -- !-- 仔细核对 gradle_runtime_dependencies.txt 文件逐一添加 -- /dependencies build plugins !-- Spring Boot Maven Plugin用于打包可执行jar -- plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin !-- Maven Compiler Plugin父POM已配置通常无需重复 -- !-- 如果需要特殊配置可以覆盖 -- plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId configuration source${java.version}/source target${java.version}/target encoding${project.build.sourceEncoding}/encoding /configuration /plugin /plugins !-- 资源文件过滤配置如果需要 -- resources resource directorysrc/main/resources/directory filteringtrue/filtering !-- 是否替换资源文件中的占位符 -- includes include**/*.properties/include include**/*.yml/include /includes /resource /resources /build /project校对关键点依赖版本核对这是最容易出错的地方。将生成的pom.xml中的依赖与gradle_dependencies.txt报告逐一对比。重点关注那些没有从父POM继承版本的依赖如Lombok、某些工具类库。确保版本号一致。Maven的依赖传递机制和Gradle不同有时需要显式声明某个传递依赖的版本以避免冲突。Scope映射核对根据2.1节的映射关系检查每个依赖的scope是否正确。特别是provided和runtime弄错会导致编译错误或打包体积过大。插件功能替代在Gradle中java插件自动完成了编译、测试、打包等任务。在Maven中这是由maven-compiler-plugin,maven-surefire-plugin,maven-jar-plugin等完成的。如果你继承了spring-boot-starter-parent这些插件都已预配置好。否则你需要手动添加和配置它们。仓库配置如果Gradle项目配置了阿里云、华为云等镜像仓库你需要在Maven的settings.xml用户全局或项目级或pom.xml的repositories中配置对应的镜像以加速依赖下载。4. 构建验证与常见问题排错生成并完善pom.xml后绝不能假设迁移已经成功。必须通过严格的构建和测试来验证。4.1 执行Maven构建生命周期在包含pom.xml的根目录下打开新的终端避免Gradle环境变量干扰执行标准构建命令mvn clean compile此命令清理旧编译结果并编译主代码。这是第一道关卡可以检查编译时依赖compilescope是否齐全语法是否兼容。mvn clean test此命令编译并运行所有测试。这是验证迁移是否成功的黄金标准。如果所有测试通过说明代码的核心功能在Maven环境下运行正常。测试依赖testscope是否正确配置也在此环节验证。mvn clean package此命令执行完整构建并打包生成target/*.jar或target/*.war。这会验证运行时依赖runtimescope和打包插件如spring-boot-maven-plugin的配置是否正确。4.2 典型问题与解决方案在验证过程中你几乎一定会遇到一些问题。以下是几个高频问题及其排查思路问题一依赖找不到Could not resolve dependencies现象mvn compile失败提示某个artifactId或version在仓库中不存在。排查检查pom.xml中该依赖的groupId,artifactId,version是否拼写正确。去 Maven中央仓库 或你配置的镜像仓库网页搜索该坐标确认是否存在。特别关注版本号。Gradle有时可以使用表示动态版本或者通过platform/BOM管理版本。Maven中需要固定具体的版本号或者通过dependencyManagement导入BOM。检查是否需要添加特定的repository比如有些公司私有库或Spring Milestone仓库。问题二类找不到ClassNotFoundException或NoClassDefFoundError现象编译成功但运行测试或启动应用时抛类找不到异常。排查Scope错误最可能的原因。一个在Gradle中是implementation的依赖在Maven中被错误地声明为provided或test。回顾2.1节的映射修正scope。依赖缺失某个必要的传递依赖在Maven的依赖树中没有被引入。使用mvn dependency:tree命令查看完整的依赖树与Gradle的dependencies输出对比找到缺失的依赖并显式声明。包路径冲突罕见的包名/类名冲突。使用mvn dependency:tree -Dverbose查看冲突并用exclusions排除不需要的传递依赖。问题三测试失败现象mvn test失败但之前gradle test是成功的。排查测试依赖确认所有测试专用的依赖如JUnit 5的junit-jupiter-api,junit-jupiter-engineMockito等都已正确添加且scope为test。测试资源Gradle的src/test/resources目录默认会被加入测试类路径。Maven同样如此。但如果你的测试代码动态读取资源文件注意路径差异。可以使用getClass().getResource(/file.txt)来获取。系统属性或环境变量有些测试可能依赖通过Gradletest任务设置的JVM系统属性。在Maven中需要在maven-surefire-plugin配置中设置plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-surefire-plugin/artifactId configuration systemPropertyVariables your.property.keyproperty-value/your.property.key /systemPropertyVariables /configuration /plugin问题四打包结果不正确现象mvn package生成的jar/war文件无法运行或缺少资源文件。排查可执行Jar对于Spring Boot项目必须使用spring-boot-maven-plugin否则打出来的jar没有内嵌容器和主类信息。确保该插件已配置。资源文件遗漏检查buildresources配置。默认情况下src/main/resources下的文件会被复制到target/classes并打包。如果你的资源文件在非标准位置需要在这里额外配置resource。主类清单非Spring Boot的普通可执行Jar需要在maven-jar-plugin中配置archive和manifest来指定主类。5. 多模块项目的迁移策略单模块项目的迁移相对直接。对于多模块项目迁移需要更系统的规划。核心思想是先建立Maven的父子项目结构再逐个模块迁移。5.1 建立Maven项目结构假设原Gradle项目结构如下my-multi-module-project/ ├── build.gradle ├── settings.gradle ├── module-api/ │ └── build.gradle ├── module-service/ │ └── build.gradle └── module-web/ └── build.gradle目标Maven结构my-multi-module-project/ ├── pom.xml (父POM打包类型为pom) ├── module-api/ │ ├── pom.xml │ └── src/ ├── module-service/ │ ├── pom.xml │ └── src/ └── module-web/ ├── pom.xml └── src/创建父POM在项目根目录创建pom.xml其packaging为pom并在modules中列出所有子模块。!-- 根目录 pom.xml -- project ... modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdmy-multi-module-parent/artifactId version1.0.0-SNAPSHOT/version packagingpom/packaging !-- 关键 -- modules modulemodule-api/module modulemodule-service/module modulemodule-web/module /modules !-- 在父POM中定义公共依赖管理和属性 -- dependencyManagement dependencies !-- 统一管理各子模块共用依赖的版本 -- /dependencies /dependencyManagement properties !-- 公共属性 -- /properties /project迁移子模块进入每个子模块目录如module-api使用gradle init --type pom为该模块生成独立的pom.xml。然后手动编辑这个子pom.xml添加parent指向根项目的坐标。移除父POM中已定义的公共依赖的version。将Gradle中implementation project(‘:module-api’)的依赖转换为Maven中对兄弟模块的普通依赖声明使用在子模块POM中定义的groupId和artifactId。5.2 处理模块间依赖这是多模块迁移的关键。在子模块module-service的pom.xml中如果需要依赖module-api应该这样声明!-- module-service/pom.xml -- project ... parent groupIdcom.example/groupId artifactIdmy-multi-module-parent/artifactId version1.0.0-SNAPSHOT/version /parent artifactIdmodule-service/artifactId dependencies dependency !-- 依赖兄弟模块 -- groupIdcom.example/groupId artifactIdmodule-api/artifactId version${project.version}/version !-- 版本通常与父项目一致 -- /dependency !-- 其他外部依赖 -- /dependencies /project重要提示在Maven中构建顺序由模块依赖关系自动决定。你需要先在根目录执行mvn clean install将子模块安装到本地仓库这样其他模块才能引用到。或者始终在根目录执行mvn clean compile/packageMaven会按正确顺序构建所有模块。6. 迁移后的优化与收尾工作当所有模块都能通过mvn clean test和mvn clean package后迁移的主要技术工作就完成了。但为了让项目更健壮、更符合Maven生态的最佳实践还需要做一些优化和收尾。6.1 利用Maven特性优化配置依赖管理Dependency Management在父POM中使用dependencyManagement统一管理所有子模块共用的依赖版本。这能极大避免版本冲突类似于Gradle的platform或版本目录Version Catalog。dependencyManagement dependencies dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId version${lombok.version}/version /dependency !-- 其他通用依赖 -- /dependencies /dependencyManagement子模块中引用这些依赖时可以省略version标签。插件管理Plugin Management同样在父POM中使用pluginManagement统一配置各模块共用的插件版本和配置确保构建行为一致。资源过滤与ProfileMaven的资源过滤filteringtrue/filtering功能强大可以结合profiles为不同环境dev, test, prod打包不同的配置文件。这是Gradle需要额外插件才能方便实现的功能现在可以原生用起来。6.2 清理与文档更新移除Gradle文件确认Maven构建完全稳定后可以安全删除Gradle相关的文件了build.gradle,settings.gradle,gradle.propertiesgradle/目录gradlew,gradlew.bat项目中的.gradle缓存目录通常可以忽略谨慎操作建议先使用Git等版本控制系统提交Maven化后的稳定代码然后再删除这些文件。或者先将它们移动到一个备份目录。更新IDE项目文件如果你使用IntelliJ IDEA或Eclipse需要重新导入项目。IntelliJ IDEA关闭项目。删除项目根目录下的.idea目录和所有的.iml文件。然后使用File - Open选择包含pom.xml的根目录IDEA会将其识别为Maven项目并重新导入。Eclipse删除项目不从磁盘删除。然后使用File - Import - Maven - Existing Maven Projects重新导入。更新CI/CD流水线将Jenkins、GitLab CI等持续集成脚本中的构建命令从./gradlew build改为mvn clean package。同时检查是否需要更新构建节点上的工具安装从Gradle切换到Maven。更新项目README在项目说明文档中将构建指南从Gradle命令更新为Maven命令。6.3 最后的验证清单在宣布迁移完成前运行一遍这个清单[ ]mvn clean compile成功。[ ]mvn clean test成功所有单元测试和集成测试通过。[ ]mvn clean package成功生成的jar/war包在目标环境如测试服务器可正常启动运行。[ ] 多模块项目在根目录执行mvn clean install所有模块按顺序构建成功且模块间依赖正确。[ ] IDE中项目导入正常代码无报错依赖库显示正确运行/调试配置可正常工作。[ ] 团队其他成员能用新的Maven配置成功拉取代码并构建。迁移本身是一次性的但理解两个工具背后的设计理念能让你在未来无论使用哪种工具都更加得心应手。Gradle的灵活和性能与Maven的约定和稳定各有其适用场景。这次转换过程实际上是一次对项目构建生命周期的深度梳理往往能发现并清理掉一些陈旧的、不必要的依赖或配置让项目结构变得更加清晰。
