拓冰网站定制 
接手一个老项目第一件事往往是看它的构建文件而不是先翻业务代码。如果你打开项目发现根部躺着一个pom.xml但里面既没有spring-boot-starter-parent也没有任何 Spring Boot 相关的依赖那就说明这还是一个传统 Maven 项目——也就是 Spring MVC 外部 Servlet 容器最常见的是 Tomcat那种组合。把这样一个 Maven 项目改造成 Spring Boot 项目是我这几年做过很多次的操作说不上难但坑确实不少。很多人以为把依赖换掉、加个启动类就完事了结果一跑起来全是问题配置不生效、JSP 找不到、静态资源 404、Mapper没被扫描。这篇文章就围绕“Maven 项目变成 SpringBoot 项目”这个场景把完整的改造过程、每一步背后的原因、以及我实践里踩过的坑一次性讲清楚。1. 内容整体设计与思路拆解1.1 改造的本质不是重写而是换一套“装配方式”先说清楚一个基本概念Maven 是构建工具Spring Boot 是框架。一个 Maven 项目改成 Spring Boot 项目并不是把 Maven 扔掉恰恰相反Spring Boot 项目的依赖管理、构建打包依然全部依赖 Maven。所以要理解这次改造的本质——它改的是项目的依赖结构和启动方式而不是推翻原有的业务代码。传统 Maven 项目基于 Spring MVC通常长这样pom.xml里显式引入spring-webmvc、mybatis、druid、log4j等依赖并且要手动管理版本号。web 层靠web.xml或者Configuration配置DispatcherServlet。部署方式是打 WAR 包扔进外部 Tomcat 的webapps目录。运行前必须先装 Tomcat、改端口、配数据源环境不一致时经常出现“本地能跑、服务器上跑不了”。而 Spring Boot 项目长这样pom.xml顶部引入spring-boot-starter-parent或spring-boot-dependenciesBOM子依赖全部由它统一管理版本。启动靠一个带有main方法的类通过SpringApplication.run()启动内嵌 Tomcat。打出来的包是可直接java -jar执行的 fat JAR。配置集中在application.yml或application.properties。改造的核心动作就是把“显式配置 外部容器”换成“自动装配 内嵌容器”但你的业务代码——Service、Mapper、Controller——基本可以原封不动地搬过来。这就是我为什么说这个改造性价比很高你付出的是一次结构性调整的时间换来的是后续开发、测试、部署体验的全面升级。1.2 改造的收益为什么要折腾这一次我经常在网上看到这样的问题“项目能跑就行干嘛非要改成 Spring Boot”每次看到这种问题我都想反问一句你能跑那你的同事能跑吗你的服务器能跑吗你下次入职新公司新环境能跑吗具体来说改造成 Spring Boot 后最大的收益有四个第一依赖版本冲突问题基本消失。传统 Maven 项目最痛苦的就是版本号Spring 4.x 的某个小版本和 MyBatis 某个版本的兼容性、Jackson 与 Spring 的版本匹配全靠踩坑试出来。Spring Boot 通过spring-boot-starter-parent统一锁定了常用框架的版本你只需要在properties里声明一个java.version其余交给它。第二开发调试效率大幅提升。传统项目改个代码要重启 Tomcat改动文件多了还要重新部署一次来回少说半分钟。Spring Boot 项目配好spring-boot-devtools后改完代码自动重启从 CtrlS 到看到效果基本在三五秒内。更别提内嵌 Tomcat 不需要额外安装新同事拉下代码就能跑。第三部署方式标准化。传统打包是 WAR要检查 Tomcat 版本、配置context.xml、设置 JVM 参数每个环境都要手工操作一遍。Spring Boot 打出来是一个包含所有依赖的 jar服务器上只要有 JDK 8 以上环境一行java -jar xxx.jar就能跑起来。第四周边生态直接可用。Spring Boot 的 Actuator 监控、自动配置的配置处理器spring-boot-configuration-processor、官方文档里海量的配置说明都是传统项目享受不到的。你花半个月时间改造后续开发效率提升的回报远超这个投入。当然有一个情况我不建议改造如果项目用的是非常老的 Spring 3.x JDK 7且业务代码高度耦合了 XML 配置、自定义了多个HandlerInterceptor和Filter或者大量使用 JSP 并且短期内没有重写计划那改造的成本就会偏高。这种情况下建议先评估 JSP 页面是否要替换为模板引擎或前后端分离再决定是否动手。2. 核心细节解析与主要配置项2.1 改造前的准备工作把家底摸清楚动工之前先做三件事。第一确认 JDK 版本。Spring Boot 2.x 要求 JDK 8 起Spring Boot 3.x 要求 JDK 17 起。如果你本地还是 JDK 8且暂时不想升级老老实实用 Spring Boot 2.7.x 系列的最后一个版本它既稳定又不会强迫你升级 JDK。如果你已经用上 JDK 17直接上 3.x 没问题但要注意部分第三方框架的兼容性。第二梳理当前项目的依赖清单。在项目根目录执行mvn dependency:list deps.txt把当前所有依赖列出来对照着看哪些是 Spring Boot 已经帮你管好版本的哪些是完全没有对应 starter、需要手动引入的。我实际操作中处理过一个项目里面引入了commons-lang3、fastjson、poi、hanlp这些非 Spring 生态的库改造时这些依赖保留原样因为它们跟 Spring Boot 没有冲突只是版本号要手动指定。第三看一眼src/main/resources目录里有哪些配置文件。Spring Boot 默认支持application.properties和application.yml也支持自定义文件通过PropertySource加载。但要注意Spring Boot 对配置文件的加载顺序和覆盖机制有自己的一套逻辑后面我会专门讲。2.2 核心改造步骤pom.xml 是重头戏整个改造过程可以分为五个核心环节其中pom.xml的修改是最关键的也是大多数人最容易搞砸的地方。第一步把原来的parent段落替换成spring-boot-starter-parent。很多老项目压根没有parent那么直接新增一段parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent这一步相当于把你项目的所有依赖版本管理权交给了 Spring Boot。有人会问那万一我要用的某个库 Spring Boot 没管理怎么办很简单在dependency里显式加上version即可显式指定的优先级是最高的。第二步调整packaging。改成 Spring Boot 项目后默认打包方式是 jar所以packagingwar/packaging这一行要么删掉、要么改成packagingjar/packaging。当然你会问如果我的项目还需要部署到外部 Tomcat 怎么办Spring Boot 也支持打包成 war但需要额外配置SpringBootServletInitializer这个后面讲。第三步替换和添加依赖。原来的spring-webmvc、spring-core、spring-context这些直接删掉换成spring-boot-starter-web原来的mybatis换成mybatis-spring-boot-starter这个是 MyBatis 官方提供的不是 Spring Boot 官方的版本号要自己指定原来的druid换成druid-spring-boot-starter同样来自阿里巴巴不是 Spring Boot 官方的。加数据库相关就加spring-boot-starter-jdbc。这里插一句很多人会问“starter 到底是个什么东西”。简单说spring-boot-starter-web本身不是一个具体功能的实现而是一个打包好的依赖集合里面包含了spring-webmvc、spring-web、内嵌 Tomcat、Jackson JSON 序列化库等一整套 Web 开发必备的依赖。你引入一个 starter就等于宣告“我要用 Web 功能请你把相关的依赖和自动配置都给我安排好”。这个机制和 Maven 的依赖传递是天生契合的。第四步加入 Maven 插件。这一步很多人会漏掉导致打出 jar 包后执行java -jar时报 “no main manifest attribute” 错误。需要在build里加build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build这个插件在package阶段会把依赖全部打进 jar并生成MANIFEST.MF里的Main-Class和Start-Class属性让 jar 可以直接执行。第五步也是最容易出问题的一步——处理完pom.xml后立即刷新 Maven 工程并检查依赖树。在 IDEA 里点右侧 Maven 面板的刷新按钮或者在命令行执行mvn clean install -DskipTests观察控制台是否有依赖冲突警告尤其是 Jackson 版本冲突和日志框架冲突。2.3 依赖版本选择与配置文件迁移依赖版本这里我强烈建议大家优先使用 Spring Boot 已管理的版本。什么意思就是凡是不写version就能通过 Spring Boot BOM 拿到版本号的依赖一律不要再手写版本号。原因很简单Spring Boot 团队在发布每个版本时都会对它所管理的所有依赖做完整兼容性测试你用手写版本号等于主动放弃了这层保障。但有两类依赖必须手动指定版本。第一类是 Spring Boot 根本没有提供 starter 的库比如minio对象存储、hanlpNLP 分词、kettleETL 工具这些你用的时候照常引入即可不会影响 Spring Boot 的自动装配。第二类是某些你明确知道要特殊版本的库比如有时你需要一个比 Spring Boot 默认版本更新的 Jackson那就显式指定。配置文件迁移也是重头戏。原来的项目如果有web.xml、spring-mvc.xml、spring-mybatis.xml这些 XML 配置改造时优先把它们的内容换成 Java Config 或者直接在application.yml里声明。这里有一个经验法则与数据库连接相关的配置数据源 URL、用户名、密码迁到application.yml的spring.datasource下。与 MyBatis 相关的配置mapper 文件位置、Alias 包路径迁到mybatis配置节点下Spring Boot 读取的是mybatis.mapper-locations和mybatis.type-aliases-package这两个 key。与 Spring MVC 相关的配置视图解析器、静态资源路径、拦截器要么直接去掉Spring Boot 有默认值要么通过Configuration类配置。日志配置文件log4j.xml或log4j.properties可以保留但更推荐换成logback-spring.xmlSpring Boot 官方默认使用 Logback。我最早改造项目时有一个配置始终不生效——数据库连接池初始化失败报错信息提示找不到驱动类。排查了半天最后发现是因为原项目把数据库配置写在jdbc.properties里而application.yml里根本没有引用到这个属性文件。如果你保留了PropertySource这种方式Spring Boot 会正常加载但你得确保路径和编码都没问题。更稳妥的做法是把配置统一收进application.yml。3. 实操过程与核心环节实现3.1 从 pom.xml 到启动类一步一个脚印我拿一个典型的旧项目来做示例。假设这是一个基于 Spring MVC MyBatis 的考勤管理系统原来用 IDEA 的 Maven 骨架生成依赖里有spring-webmvc、mybatis、mysql-connector-java、druid部署方式还是 WAR 外部 Tomcat。改造过程按下面顺序走基本不会出大问题。先把pom.xml的parent换成 Spring Bootparent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent properties java.version1.8/java.version /properties然后把依赖里的spring-webmvc、spring-core、spring-tx等全部删除替换为dependencies !-- Web 核心 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- MyBatis -- dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.1/version /dependency !-- MySQL 驱动 -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency !-- 连接池可根据情况换成 HikariCP 去掉 druid -- dependency groupIdcom.alibaba/groupId artifactIddruid-spring-boot-starter/artifactId version1.2.20/version /dependency !-- 测试 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependenciesmysql-connector-j这个依赖是 Spring Boot 2.7.18 管理的版本在老项目里你可能用的是mysql-connector-java区别只是新版的 GA 坐标改名了功能上完全兼容。如果项目里有fastjson建议逐步替换成 Jackson——Spring Boot 默认已经引入了 Jackson两个 JSON 库同时存在容易在序列化扩展上出现奇怪问题不过如果你的业务代码大量使用了JSONObject可以暂时保留fastjson但接口返回值建议使用 Spring Boot 默认的 Jackson 序列化。接下来在src/main/java下找个合适的位置新建启动类。包名最好放在根包下比如原来的包名是com.xxx.attendance启动类就放在这个包下package com.xxx.attendance; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class AttendanceApplication { public static void main(String[] args) { SpringApplication.run(AttendanceApplication.class, args); } }SpringBootApplication是一个组合注解等于ConfigurationEnableAutoConfigurationComponentScan三个注解合体。其中最关键的是EnableAutoConfiguration它让 Spring Boot 能根据 classpath 下的依赖自动创建对应的 Bean。启动类放在根包之所以重要是因为默认的ComponentScan只扫描启动类所在包及其子包如果 Controller、Service、Mapper 放到了启动类包外面就会扫不到。3.2 配置迁移与端口调整application.yml的写法是这类项目改造中非常重要的一个环节。原来放在 Spring XML 里的配置现在几乎都能在application.yml里找到对应的 key。还是拿考勤系统举例原来spring-mybatis.xml里有这么一段bean iddataSource classorg.apache.tomcat.jdbc.pool.DataSource property nameurl valuejdbc:mysql://localhost:3306/attendance/ property nameusername valueroot/ property namepassword value123456/ /bean迁移到application.yml后server: port: 8080 servlet: context-path: / spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/attendance?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root password: 123456 druid: initial-size: 2 min-idle: 2 max-active: 20 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.xxx.attendance.entity configuration: map-underscore-to-camel-case: true这里有两个细节值得注意。第一mybatis.mapper-locations如果要指到classpath:mapper/*.xml前提是src/main/resources/mapper/目录下面确实有 mapper 文件。如果你原本的 mapper 文件放在src/main/java下面某个包里Maven 打包时默认不会把.xml文件打进 classes 目录你需要手动配置resources或者在pom.xml里把 mapper XML 所在目录纳入资源。第二password在 YAML 文件中如果以数字开头且是纯数字比如123456会被解析成整数加引号是最稳妥的做法。如果你不想用application.yml也可以用application.properties两者效果一样只是语法风格不同。我建议新项目一律用 YAML因为它的嵌套结构在表达配置层次时比 properties 清晰得多——配置项一旦多起来properties 文件那种扁平的 key-value 格式阅读成本会急剧升高。3.3 包结构调整与注解替换不可忽略的关键操作改完配置接下来就是把原来基于 XML 的 Bean 声明转换成基于注解的 Bean 或自动配置。这个过程最花时间。我总结了一个操作清单Spring MVC 的Controller、Service、Repository这些注解保持不变不需要动。MyBatis 的 Mapper 接口原来如果在 XML 里用mapper配置的改造后要么给接口加Mapper注解要么在启动类上加MapperScan(com.xxx.attendance.mapper)。两者选其一即可同时使用也不冲突但我一般倾向用MapperScan因为一行注解能扫描整个包不用每个接口单独加。原来 Spring XML 里配置的拦截器、过滤器如果是以mvc:interceptors配置的需要改为在Configuration类里重写WebMvcConfigurer的addInterceptors方法。原来通过context:component-scan base-package.../扫描的包启动类的ComponentScan会覆盖同样的能力无需额外配置。替换完注解后还有一个很多项目都会遇到的坑原来的 Controller 依赖了 HttpServletRequest 的某些非标准方法。这部分代码不受 Spring Boot 影响但如果你在改造中一并升级了 Servlet API 版本Spring Boot 2.7 对应 Servlet 4.0 约定某些方法可能会标记为 deprecated。不影响功能但建议顺手清理。说到包结构再提一个被我反复确认过很多次的问题Spring Boot 默认扫描范围是启动类所在的包。这意味着如果你的项目原来把 Controller 放在com.xxx.controllerService 放在com.xxx.service而启动类放在了com.xxx那没问题能扫到。但如果你把启动类放到了com.xxx.attendance下面Controller 却放在com.xxx.controller下面那就扫不到了。前者是很多老项目常见的包名后者是新手常见的失误。我处理过不少改造到一半的求助帖都是这个原因导致 404。3.4 打包验证与部署实战改造完成后在 IDEA 右侧 Maven 面板双击clean和package或者在项目根目录执行mvn clean package -DskipTests如果pom.xml配置正确target目录下会生成两个文件一个叫xxx-0.0.1-SNAPSHOT.jar另一个叫xxx-0.0.1-SNAPSHOT.jar.original。前者是 Spring Boot 的 fat jar包含所有依赖后者是 Maven 原始打的瘦 jar一般用不上可以直接忽略。启动验证时直接执行java -jar target/xxx-0.0.1-SNAPSHOT.jar如果看到 Spring Boot 的横幅和Tomcat started on port(s): 8080日志说明启动成功。然后访问http://localhost:8080/验证页面。这里提醒一句如果原来的项目配置了 context-path比如访问路径是http://localhost:8080/attendance/改造后application.yml里要显式配置server.servlet.context-path: /attendance否则迁移后全部路由都变到根路径前端请求直接全部 404。还有一类情况是原来项目用了 JSP 做视图。Spring Boot 对 JSP 的支持很别扭内嵌 Tomcat 默认不支持 JSP需要额外加依赖tomcat-embed-jasper而且要放到src/main/webapp目录下。JSP 不是不能支持但维护体验和 Spring Boot 倡导的模板引擎自洽体系差距明显。如果你想彻底拥抱 Spring BootJSP 换成 Thymeleaf 才是长远之策。如果业务上 JSP 太多一时换不完那至少先把tomcat-embed-jasper加上让它能跑起来后续再逐步替换。部署到服务器时注意服务器的防火墙端口要放行JDK 版本要和本地一致。实际操作中我最常遇到的服务器问题就是 JDK 版本不一致——本地 JDK 17 编译的 jar 扔到 JDK 8 服务器上启动直接报UnsupportedClassVersionError这种问题通常出现在 Spring Boot 3.x 项目上。部署前先java -version确认环境一分钟的事能帮你省下半小时的排错时间。4. 常见问题与排查技巧实录4.1 启动即报错ClassNotFoundException 与 Bean 扫描不全改造后第一次启动最常见的就是各种ClassNotFoundException和NoSuchBeanDefinitionException。先说ClassNotFoundException。这类错误绝大多数是依赖没引全或者版本不兼容导致的。比如报错消息里有org.springframework.web.servlet.DispatcherServlet说明spring-webmvc没有正确引入——检查一下是否真的用了spring-boot-starter-web或者是否因为手动排除依赖把关键的传递依赖删掉了。再比如com.mysql.cj.jdbc.Driver找不到一般都是mysql-connector-j依赖没加进来。再说NoSuchBeanDefinitionException。这个错误常见于启动成功后业务代码调用 Bean 时报错。排查顺序是确认是否加了Service、Repository、Component注解。确认启动类包路径是否覆盖了你定义的 Bean 包。确认如果是Mapper加在接口而不是类上扫描方式是否用对了——MapperScan扫的是接口包ComponentScan扫的是类包。这类问题 90% 都是扫描范围问题。你可以通过在启动类上加一行调试输出快速判断ComponentScan(com.xxx)但如果你的项目结构本来就混乱我更建议直接重构包名把所有代码收拢到统一根包下而不是靠扫描范围到处兜底。4.2 端口冲突与配置未生效端口被占用是另一个高频问题。Spring Boot 默认 8080如果本机已经跑了别的服务启动日志会报Port 8080 was already in use。解决办法很简单改端口或者杀掉占用进程。改端口在application.ymlserver: port: 8081如果是杀进程在 Windows 上netstat -ano | findstr 8080 taskkill /PID PID /F在 Linux/macOS 上lsof -i :8080 kill -9 PID配置未生效的问题则需要排查一下你的application.yml是否真的在 classpath 根路径下。Maven 项目的资源文件默认放在src/main/resources这是对的。但有些老项目把配置文件放在src/main/webapp或者项目根目录下改造后这些位置的文件不会被 Spring Boot 默认加载。检查方法很简单——看一眼打出的 jar 包里BOOT-INF/classes/下面有没有application.yml。没有就说明资源没有自动拷贝需要手动在pom.xml的buildresources里声明。4.3 mapper XML 找不到与静态资源 404MyBatis 的 mapper XML 找不到这类问题在 Maven 项目改造成 Spring Boot 时特别常见。原因我之前提到过Maven 默认只把src/main/resources下的文件作为 classpath 资源放在src/main/java下的 XML 文件不会被打进目标目录。如果你之前是这么放的有两个解法二选一即可解法一把 mapper XML 移动到src/main/resources/mapper/下并在application.yml里配置mybatis: mapper-locations: classpath:mapper/*.xml解法二在pom.xml中显式声明把 java 目录下的 XML 也作为资源打入build resources resource directorysrc/main/java/directory includes include**/*.xml/include /includes /resource /resources /build我推荐解法一因为把代码文件和配置文件混放在一起本身就不利于管理你迟早会为这个决定付出代价。静态资源 404 的问题本质上是路径变了。原来放在webapp/下的css、js、imagesSpring Boot 默认把它们映射到了classpath:/static/还有public/、resources/、META-INF/resources/三个默认位置。所以你需要把这部分静态文件移到src/main/resources/static/下然后访问路径直接就是/css/xxx.css。4.4 一个真实案例考勤系统改造全记录有一次帮朋友改造一个基于 Spring MVC 的校园教职员工考勤系统原项目结构非常典型pom.xml里一堆手写版本号的依赖web.xml 三个 Spring XML 配置JSP 放在webapp下接口返回ModelAndView。我按前面的步骤一步步改整个过程中遇到三个问题第一个问题是 MyBatis 的SqlSessionFactory冲突。原来项目里手动配置了SqlSessionFactoryBeanSpring Boot 的mybatis-spring-boot-starter也会自动创建一个两个 Bean 共存导致启动时抛ConflictingBeanDefinitionException。解决方法是把原来 XML 或 Java Config 里手动声明的SqlSessionFactoryBean和MapperScannerConfigurer全部删掉完全交给 starter 自动配置。第二个问题是 Druid 监控页面 404。原来用 Druid 的StatViewServlet配了/druid/*。改造后这类配置改成在application.yml里配置spring.datasource.druid.stat-view-servlet相关属性即可启动内嵌的 Servlet不再需要手动注册。第三个问题是 JSP 页面全部 500。加了tomcat-embed-jasper后依旧报错最后发现是缺少javax.servlet:jstl依赖补上以后就正常了。这里顺便提醒Spring Boot 2.x 里 Servlet API 是javax.servletSpring Boot 3.x 换成了jakarta.servlet你网上搜到的很多资料默认是javax版本对不上就会踩坑。4.5 问题速查表我整理了一份高频问题对照表方便你在改造时快速定位现象大概率原因处理办法启动类找不到 Spring 的类依赖没转换完整检查pom.xml是否引入spring-boot-starter-webController 全部 404启动类包路径不在 Controller 包的上层调整启动类位置或加ComponentScanMapper 扫描不到未加Mapper也未加MapperScan在启动类加MapperScan(你的mapper包路径)mapper XML 未执行XML 不在 classpath 中把 XML 移到resources/mapper/下配置mybatis.mapper-locations端口被占用本机已有进程占用 8080换 port 或杀进程见上文命令druid 相关配置不生效引入了 druid 但没引druid-spring-boot-starter替换或补充依赖JSP 页面 500缺少tomcat-embed-jasper或jstl依赖补依赖确认版本与javax/jakarta对应配置文件不生效配置文件不在src/main/resources/下移动位置或配置resourcesjar 包执行报 “no main manifest attribute”缺spring-boot-maven-plugin在build中补插件UnsupportedClassVersionError编译 JDK 与运行 JDK 不一致统一本地和服务器 JDK 版本5. 改造后的收尾体验几个我反复用的小技巧改造完成不等于彻底结束有几件事我建议你在收尾阶段顺手做掉它们能明显提升后续使用体验。第一个是控制台输出。Spring Boot 默认启动时会打印一个 ASCII 风格的 banner很多人觉得好看但如果你只是为了看日志它可以完全关掉。在application.yml里配置spring: main: banner-mode: off或者更彻底一点把 banner 放在src/main/resources/banner.txt里自定义——网上有在线 banner 生成器随便输入几个字母公司项目里写上项目名个人项目里写个搞笑的句子每天启动时看一眼还挺提神。第二个是热部署。在pom.xml里加一个开发期依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId scoperuntime/scope optionaltrue/optional /dependency加上后IDEA 中修改代码后 CtrlF9Build ProjectSpring Boot 应用会自动重启省去手动 kill 再 start 的时间成本。但注意一点打生产 jar 包时记得保证这个依赖不会被打进去。scoperuntime/scope加上mvn package时它会出现在依赖列表里实际执行java -jar时如果不需要可以加 JVM 参数-Dspring.devtools.restart.enabledfalse关闭。更干净的做法是把 devtools 排除出生产包这个在spring-boot-maven-plugin里用excludeDevtoolstrue/excludeDevtools即可。第三件事是配置多环境。这是传统 Maven 项目改造后体验提升最明显的一点。以前搞多环境靠的是 Maven profile 里配一堆properties然后 filter 替换麻烦不说还容易出错。Spring Boot 原生支持用文件名后缀区分环境application-dev.yml application-prod.yml然后在application.yml里指定激活哪个spring: profiles: active: dev这样不同环境的数据库连接、日志级别、服务端口就能干净地分离。我在实际项目里会把没加active的application.yml作为兜底默认配置这样本地直接启动不会因为缺少配置而崩掉。最后说一个我的个人习惯改造完成后在 Git 里单独开一个分支提交commit 信息写清楚每一步做了什么。这个习惯帮我解决过不少问题——有一次改造到一半发现后续需求迭代需要旧版本的代码支撑直接切回旧分支就行不需要回滚一堆文件。改造这种事做完不是重点做得可控才是重点。如果你手里也有一个跑了好几年的 Maven 老项目我的建议很简单别犹豫改吧。这个改造不会让你的业务代码一夜间焕然一新但它会让你的日常开发和项目维护顺畅一个台阶。既然迟早要做趁项目还处于功能稳定期动手成本最低。 Maven项目改造Spring Boot全流程解析与踩坑指南
接手一个老项目第一件事往往是看它的构建文件而不是先翻业务代码。如果你打开项目发现根部躺着一个pom.xml但里面既没有spring-boot-starter-parent也没有任何 Spring Boot 相关的依赖那就说明这还是一个传统 Maven 项目——也就是 Spring MVC 外部 Servlet 容器最常见的是 Tomcat那种组合。把这样一个 Maven 项目改造成 Spring Boot 项目是我这几年做过很多次的操作说不上难但坑确实不少。很多人以为把依赖换掉、加个启动类就完事了结果一跑起来全是问题配置不生效、JSP 找不到、静态资源 404、Mapper没被扫描。这篇文章就围绕“Maven 项目变成 SpringBoot 项目”这个场景把完整的改造过程、每一步背后的原因、以及我实践里踩过的坑一次性讲清楚。1. 内容整体设计与思路拆解1.1 改造的本质不是重写而是换一套“装配方式”先说清楚一个基本概念Maven 是构建工具Spring Boot 是框架。一个 Maven 项目改成 Spring Boot 项目并不是把 Maven 扔掉恰恰相反Spring Boot 项目的依赖管理、构建打包依然全部依赖 Maven。所以要理解这次改造的本质——它改的是项目的依赖结构和启动方式而不是推翻原有的业务代码。传统 Maven 项目基于 Spring MVC通常长这样pom.xml里显式引入spring-webmvc、mybatis、druid、log4j等依赖并且要手动管理版本号。web 层靠web.xml或者Configuration配置DispatcherServlet。部署方式是打 WAR 包扔进外部 Tomcat 的webapps目录。运行前必须先装 Tomcat、改端口、配数据源环境不一致时经常出现“本地能跑、服务器上跑不了”。而 Spring Boot 项目长这样pom.xml顶部引入spring-boot-starter-parent或spring-boot-dependenciesBOM子依赖全部由它统一管理版本。启动靠一个带有main方法的类通过SpringApplication.run()启动内嵌 Tomcat。打出来的包是可直接java -jar执行的 fat JAR。配置集中在application.yml或application.properties。改造的核心动作就是把“显式配置 外部容器”换成“自动装配 内嵌容器”但你的业务代码——Service、Mapper、Controller——基本可以原封不动地搬过来。这就是我为什么说这个改造性价比很高你付出的是一次结构性调整的时间换来的是后续开发、测试、部署体验的全面升级。1.2 改造的收益为什么要折腾这一次我经常在网上看到这样的问题“项目能跑就行干嘛非要改成 Spring Boot”每次看到这种问题我都想反问一句你能跑那你的同事能跑吗你的服务器能跑吗你下次入职新公司新环境能跑吗具体来说改造成 Spring Boot 后最大的收益有四个第一依赖版本冲突问题基本消失。传统 Maven 项目最痛苦的就是版本号Spring 4.x 的某个小版本和 MyBatis 某个版本的兼容性、Jackson 与 Spring 的版本匹配全靠踩坑试出来。Spring Boot 通过spring-boot-starter-parent统一锁定了常用框架的版本你只需要在properties里声明一个java.version其余交给它。第二开发调试效率大幅提升。传统项目改个代码要重启 Tomcat改动文件多了还要重新部署一次来回少说半分钟。Spring Boot 项目配好spring-boot-devtools后改完代码自动重启从 CtrlS 到看到效果基本在三五秒内。更别提内嵌 Tomcat 不需要额外安装新同事拉下代码就能跑。第三部署方式标准化。传统打包是 WAR要检查 Tomcat 版本、配置context.xml、设置 JVM 参数每个环境都要手工操作一遍。Spring Boot 打出来是一个包含所有依赖的 jar服务器上只要有 JDK 8 以上环境一行java -jar xxx.jar就能跑起来。第四周边生态直接可用。Spring Boot 的 Actuator 监控、自动配置的配置处理器spring-boot-configuration-processor、官方文档里海量的配置说明都是传统项目享受不到的。你花半个月时间改造后续开发效率提升的回报远超这个投入。当然有一个情况我不建议改造如果项目用的是非常老的 Spring 3.x JDK 7且业务代码高度耦合了 XML 配置、自定义了多个HandlerInterceptor和Filter或者大量使用 JSP 并且短期内没有重写计划那改造的成本就会偏高。这种情况下建议先评估 JSP 页面是否要替换为模板引擎或前后端分离再决定是否动手。2. 核心细节解析与主要配置项2.1 改造前的准备工作把家底摸清楚动工之前先做三件事。第一确认 JDK 版本。Spring Boot 2.x 要求 JDK 8 起Spring Boot 3.x 要求 JDK 17 起。如果你本地还是 JDK 8且暂时不想升级老老实实用 Spring Boot 2.7.x 系列的最后一个版本它既稳定又不会强迫你升级 JDK。如果你已经用上 JDK 17直接上 3.x 没问题但要注意部分第三方框架的兼容性。第二梳理当前项目的依赖清单。在项目根目录执行mvn dependency:list deps.txt把当前所有依赖列出来对照着看哪些是 Spring Boot 已经帮你管好版本的哪些是完全没有对应 starter、需要手动引入的。我实际操作中处理过一个项目里面引入了commons-lang3、fastjson、poi、hanlp这些非 Spring 生态的库改造时这些依赖保留原样因为它们跟 Spring Boot 没有冲突只是版本号要手动指定。第三看一眼src/main/resources目录里有哪些配置文件。Spring Boot 默认支持application.properties和application.yml也支持自定义文件通过PropertySource加载。但要注意Spring Boot 对配置文件的加载顺序和覆盖机制有自己的一套逻辑后面我会专门讲。2.2 核心改造步骤pom.xml 是重头戏整个改造过程可以分为五个核心环节其中pom.xml的修改是最关键的也是大多数人最容易搞砸的地方。第一步把原来的parent段落替换成spring-boot-starter-parent。很多老项目压根没有parent那么直接新增一段parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent这一步相当于把你项目的所有依赖版本管理权交给了 Spring Boot。有人会问那万一我要用的某个库 Spring Boot 没管理怎么办很简单在dependency里显式加上version即可显式指定的优先级是最高的。第二步调整packaging。改成 Spring Boot 项目后默认打包方式是 jar所以packagingwar/packaging这一行要么删掉、要么改成packagingjar/packaging。当然你会问如果我的项目还需要部署到外部 Tomcat 怎么办Spring Boot 也支持打包成 war但需要额外配置SpringBootServletInitializer这个后面讲。第三步替换和添加依赖。原来的spring-webmvc、spring-core、spring-context这些直接删掉换成spring-boot-starter-web原来的mybatis换成mybatis-spring-boot-starter这个是 MyBatis 官方提供的不是 Spring Boot 官方的版本号要自己指定原来的druid换成druid-spring-boot-starter同样来自阿里巴巴不是 Spring Boot 官方的。加数据库相关就加spring-boot-starter-jdbc。这里插一句很多人会问“starter 到底是个什么东西”。简单说spring-boot-starter-web本身不是一个具体功能的实现而是一个打包好的依赖集合里面包含了spring-webmvc、spring-web、内嵌 Tomcat、Jackson JSON 序列化库等一整套 Web 开发必备的依赖。你引入一个 starter就等于宣告“我要用 Web 功能请你把相关的依赖和自动配置都给我安排好”。这个机制和 Maven 的依赖传递是天生契合的。第四步加入 Maven 插件。这一步很多人会漏掉导致打出 jar 包后执行java -jar时报 “no main manifest attribute” 错误。需要在build里加build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build这个插件在package阶段会把依赖全部打进 jar并生成MANIFEST.MF里的Main-Class和Start-Class属性让 jar 可以直接执行。第五步也是最容易出问题的一步——处理完pom.xml后立即刷新 Maven 工程并检查依赖树。在 IDEA 里点右侧 Maven 面板的刷新按钮或者在命令行执行mvn clean install -DskipTests观察控制台是否有依赖冲突警告尤其是 Jackson 版本冲突和日志框架冲突。2.3 依赖版本选择与配置文件迁移依赖版本这里我强烈建议大家优先使用 Spring Boot 已管理的版本。什么意思就是凡是不写version就能通过 Spring Boot BOM 拿到版本号的依赖一律不要再手写版本号。原因很简单Spring Boot 团队在发布每个版本时都会对它所管理的所有依赖做完整兼容性测试你用手写版本号等于主动放弃了这层保障。但有两类依赖必须手动指定版本。第一类是 Spring Boot 根本没有提供 starter 的库比如minio对象存储、hanlpNLP 分词、kettleETL 工具这些你用的时候照常引入即可不会影响 Spring Boot 的自动装配。第二类是某些你明确知道要特殊版本的库比如有时你需要一个比 Spring Boot 默认版本更新的 Jackson那就显式指定。配置文件迁移也是重头戏。原来的项目如果有web.xml、spring-mvc.xml、spring-mybatis.xml这些 XML 配置改造时优先把它们的内容换成 Java Config 或者直接在application.yml里声明。这里有一个经验法则与数据库连接相关的配置数据源 URL、用户名、密码迁到application.yml的spring.datasource下。与 MyBatis 相关的配置mapper 文件位置、Alias 包路径迁到mybatis配置节点下Spring Boot 读取的是mybatis.mapper-locations和mybatis.type-aliases-package这两个 key。与 Spring MVC 相关的配置视图解析器、静态资源路径、拦截器要么直接去掉Spring Boot 有默认值要么通过Configuration类配置。日志配置文件log4j.xml或log4j.properties可以保留但更推荐换成logback-spring.xmlSpring Boot 官方默认使用 Logback。我最早改造项目时有一个配置始终不生效——数据库连接池初始化失败报错信息提示找不到驱动类。排查了半天最后发现是因为原项目把数据库配置写在jdbc.properties里而application.yml里根本没有引用到这个属性文件。如果你保留了PropertySource这种方式Spring Boot 会正常加载但你得确保路径和编码都没问题。更稳妥的做法是把配置统一收进application.yml。3. 实操过程与核心环节实现3.1 从 pom.xml 到启动类一步一个脚印我拿一个典型的旧项目来做示例。假设这是一个基于 Spring MVC MyBatis 的考勤管理系统原来用 IDEA 的 Maven 骨架生成依赖里有spring-webmvc、mybatis、mysql-connector-java、druid部署方式还是 WAR 外部 Tomcat。改造过程按下面顺序走基本不会出大问题。先把pom.xml的parent换成 Spring Bootparent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent properties java.version1.8/java.version /properties然后把依赖里的spring-webmvc、spring-core、spring-tx等全部删除替换为dependencies !-- Web 核心 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- MyBatis -- dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.1/version /dependency !-- MySQL 驱动 -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency !-- 连接池可根据情况换成 HikariCP 去掉 druid -- dependency groupIdcom.alibaba/groupId artifactIddruid-spring-boot-starter/artifactId version1.2.20/version /dependency !-- 测试 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependenciesmysql-connector-j这个依赖是 Spring Boot 2.7.18 管理的版本在老项目里你可能用的是mysql-connector-java区别只是新版的 GA 坐标改名了功能上完全兼容。如果项目里有fastjson建议逐步替换成 Jackson——Spring Boot 默认已经引入了 Jackson两个 JSON 库同时存在容易在序列化扩展上出现奇怪问题不过如果你的业务代码大量使用了JSONObject可以暂时保留fastjson但接口返回值建议使用 Spring Boot 默认的 Jackson 序列化。接下来在src/main/java下找个合适的位置新建启动类。包名最好放在根包下比如原来的包名是com.xxx.attendance启动类就放在这个包下package com.xxx.attendance; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class AttendanceApplication { public static void main(String[] args) { SpringApplication.run(AttendanceApplication.class, args); } }SpringBootApplication是一个组合注解等于ConfigurationEnableAutoConfigurationComponentScan三个注解合体。其中最关键的是EnableAutoConfiguration它让 Spring Boot 能根据 classpath 下的依赖自动创建对应的 Bean。启动类放在根包之所以重要是因为默认的ComponentScan只扫描启动类所在包及其子包如果 Controller、Service、Mapper 放到了启动类包外面就会扫不到。3.2 配置迁移与端口调整application.yml的写法是这类项目改造中非常重要的一个环节。原来放在 Spring XML 里的配置现在几乎都能在application.yml里找到对应的 key。还是拿考勤系统举例原来spring-mybatis.xml里有这么一段bean iddataSource classorg.apache.tomcat.jdbc.pool.DataSource property nameurl valuejdbc:mysql://localhost:3306/attendance/ property nameusername valueroot/ property namepassword value123456/ /bean迁移到application.yml后server: port: 8080 servlet: context-path: / spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/attendance?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root password: 123456 druid: initial-size: 2 min-idle: 2 max-active: 20 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.xxx.attendance.entity configuration: map-underscore-to-camel-case: true这里有两个细节值得注意。第一mybatis.mapper-locations如果要指到classpath:mapper/*.xml前提是src/main/resources/mapper/目录下面确实有 mapper 文件。如果你原本的 mapper 文件放在src/main/java下面某个包里Maven 打包时默认不会把.xml文件打进 classes 目录你需要手动配置resources或者在pom.xml里把 mapper XML 所在目录纳入资源。第二password在 YAML 文件中如果以数字开头且是纯数字比如123456会被解析成整数加引号是最稳妥的做法。如果你不想用application.yml也可以用application.properties两者效果一样只是语法风格不同。我建议新项目一律用 YAML因为它的嵌套结构在表达配置层次时比 properties 清晰得多——配置项一旦多起来properties 文件那种扁平的 key-value 格式阅读成本会急剧升高。3.3 包结构调整与注解替换不可忽略的关键操作改完配置接下来就是把原来基于 XML 的 Bean 声明转换成基于注解的 Bean 或自动配置。这个过程最花时间。我总结了一个操作清单Spring MVC 的Controller、Service、Repository这些注解保持不变不需要动。MyBatis 的 Mapper 接口原来如果在 XML 里用mapper配置的改造后要么给接口加Mapper注解要么在启动类上加MapperScan(com.xxx.attendance.mapper)。两者选其一即可同时使用也不冲突但我一般倾向用MapperScan因为一行注解能扫描整个包不用每个接口单独加。原来 Spring XML 里配置的拦截器、过滤器如果是以mvc:interceptors配置的需要改为在Configuration类里重写WebMvcConfigurer的addInterceptors方法。原来通过context:component-scan base-package.../扫描的包启动类的ComponentScan会覆盖同样的能力无需额外配置。替换完注解后还有一个很多项目都会遇到的坑原来的 Controller 依赖了 HttpServletRequest 的某些非标准方法。这部分代码不受 Spring Boot 影响但如果你在改造中一并升级了 Servlet API 版本Spring Boot 2.7 对应 Servlet 4.0 约定某些方法可能会标记为 deprecated。不影响功能但建议顺手清理。说到包结构再提一个被我反复确认过很多次的问题Spring Boot 默认扫描范围是启动类所在的包。这意味着如果你的项目原来把 Controller 放在com.xxx.controllerService 放在com.xxx.service而启动类放在了com.xxx那没问题能扫到。但如果你把启动类放到了com.xxx.attendance下面Controller 却放在com.xxx.controller下面那就扫不到了。前者是很多老项目常见的包名后者是新手常见的失误。我处理过不少改造到一半的求助帖都是这个原因导致 404。3.4 打包验证与部署实战改造完成后在 IDEA 右侧 Maven 面板双击clean和package或者在项目根目录执行mvn clean package -DskipTests如果pom.xml配置正确target目录下会生成两个文件一个叫xxx-0.0.1-SNAPSHOT.jar另一个叫xxx-0.0.1-SNAPSHOT.jar.original。前者是 Spring Boot 的 fat jar包含所有依赖后者是 Maven 原始打的瘦 jar一般用不上可以直接忽略。启动验证时直接执行java -jar target/xxx-0.0.1-SNAPSHOT.jar如果看到 Spring Boot 的横幅和Tomcat started on port(s): 8080日志说明启动成功。然后访问http://localhost:8080/验证页面。这里提醒一句如果原来的项目配置了 context-path比如访问路径是http://localhost:8080/attendance/改造后application.yml里要显式配置server.servlet.context-path: /attendance否则迁移后全部路由都变到根路径前端请求直接全部 404。还有一类情况是原来项目用了 JSP 做视图。Spring Boot 对 JSP 的支持很别扭内嵌 Tomcat 默认不支持 JSP需要额外加依赖tomcat-embed-jasper而且要放到src/main/webapp目录下。JSP 不是不能支持但维护体验和 Spring Boot 倡导的模板引擎自洽体系差距明显。如果你想彻底拥抱 Spring BootJSP 换成 Thymeleaf 才是长远之策。如果业务上 JSP 太多一时换不完那至少先把tomcat-embed-jasper加上让它能跑起来后续再逐步替换。部署到服务器时注意服务器的防火墙端口要放行JDK 版本要和本地一致。实际操作中我最常遇到的服务器问题就是 JDK 版本不一致——本地 JDK 17 编译的 jar 扔到 JDK 8 服务器上启动直接报UnsupportedClassVersionError这种问题通常出现在 Spring Boot 3.x 项目上。部署前先java -version确认环境一分钟的事能帮你省下半小时的排错时间。4. 常见问题与排查技巧实录4.1 启动即报错ClassNotFoundException 与 Bean 扫描不全改造后第一次启动最常见的就是各种ClassNotFoundException和NoSuchBeanDefinitionException。先说ClassNotFoundException。这类错误绝大多数是依赖没引全或者版本不兼容导致的。比如报错消息里有org.springframework.web.servlet.DispatcherServlet说明spring-webmvc没有正确引入——检查一下是否真的用了spring-boot-starter-web或者是否因为手动排除依赖把关键的传递依赖删掉了。再比如com.mysql.cj.jdbc.Driver找不到一般都是mysql-connector-j依赖没加进来。再说NoSuchBeanDefinitionException。这个错误常见于启动成功后业务代码调用 Bean 时报错。排查顺序是确认是否加了Service、Repository、Component注解。确认启动类包路径是否覆盖了你定义的 Bean 包。确认如果是Mapper加在接口而不是类上扫描方式是否用对了——MapperScan扫的是接口包ComponentScan扫的是类包。这类问题 90% 都是扫描范围问题。你可以通过在启动类上加一行调试输出快速判断ComponentScan(com.xxx)但如果你的项目结构本来就混乱我更建议直接重构包名把所有代码收拢到统一根包下而不是靠扫描范围到处兜底。4.2 端口冲突与配置未生效端口被占用是另一个高频问题。Spring Boot 默认 8080如果本机已经跑了别的服务启动日志会报Port 8080 was already in use。解决办法很简单改端口或者杀掉占用进程。改端口在application.ymlserver: port: 8081如果是杀进程在 Windows 上netstat -ano | findstr 8080 taskkill /PID PID /F在 Linux/macOS 上lsof -i :8080 kill -9 PID配置未生效的问题则需要排查一下你的application.yml是否真的在 classpath 根路径下。Maven 项目的资源文件默认放在src/main/resources这是对的。但有些老项目把配置文件放在src/main/webapp或者项目根目录下改造后这些位置的文件不会被 Spring Boot 默认加载。检查方法很简单——看一眼打出的 jar 包里BOOT-INF/classes/下面有没有application.yml。没有就说明资源没有自动拷贝需要手动在pom.xml的buildresources里声明。4.3 mapper XML 找不到与静态资源 404MyBatis 的 mapper XML 找不到这类问题在 Maven 项目改造成 Spring Boot 时特别常见。原因我之前提到过Maven 默认只把src/main/resources下的文件作为 classpath 资源放在src/main/java下的 XML 文件不会被打进目标目录。如果你之前是这么放的有两个解法二选一即可解法一把 mapper XML 移动到src/main/resources/mapper/下并在application.yml里配置mybatis: mapper-locations: classpath:mapper/*.xml解法二在pom.xml中显式声明把 java 目录下的 XML 也作为资源打入build resources resource directorysrc/main/java/directory includes include**/*.xml/include /includes /resource /resources /build我推荐解法一因为把代码文件和配置文件混放在一起本身就不利于管理你迟早会为这个决定付出代价。静态资源 404 的问题本质上是路径变了。原来放在webapp/下的css、js、imagesSpring Boot 默认把它们映射到了classpath:/static/还有public/、resources/、META-INF/resources/三个默认位置。所以你需要把这部分静态文件移到src/main/resources/static/下然后访问路径直接就是/css/xxx.css。4.4 一个真实案例考勤系统改造全记录有一次帮朋友改造一个基于 Spring MVC 的校园教职员工考勤系统原项目结构非常典型pom.xml里一堆手写版本号的依赖web.xml 三个 Spring XML 配置JSP 放在webapp下接口返回ModelAndView。我按前面的步骤一步步改整个过程中遇到三个问题第一个问题是 MyBatis 的SqlSessionFactory冲突。原来项目里手动配置了SqlSessionFactoryBeanSpring Boot 的mybatis-spring-boot-starter也会自动创建一个两个 Bean 共存导致启动时抛ConflictingBeanDefinitionException。解决方法是把原来 XML 或 Java Config 里手动声明的SqlSessionFactoryBean和MapperScannerConfigurer全部删掉完全交给 starter 自动配置。第二个问题是 Druid 监控页面 404。原来用 Druid 的StatViewServlet配了/druid/*。改造后这类配置改成在application.yml里配置spring.datasource.druid.stat-view-servlet相关属性即可启动内嵌的 Servlet不再需要手动注册。第三个问题是 JSP 页面全部 500。加了tomcat-embed-jasper后依旧报错最后发现是缺少javax.servlet:jstl依赖补上以后就正常了。这里顺便提醒Spring Boot 2.x 里 Servlet API 是javax.servletSpring Boot 3.x 换成了jakarta.servlet你网上搜到的很多资料默认是javax版本对不上就会踩坑。4.5 问题速查表我整理了一份高频问题对照表方便你在改造时快速定位现象大概率原因处理办法启动类找不到 Spring 的类依赖没转换完整检查pom.xml是否引入spring-boot-starter-webController 全部 404启动类包路径不在 Controller 包的上层调整启动类位置或加ComponentScanMapper 扫描不到未加Mapper也未加MapperScan在启动类加MapperScan(你的mapper包路径)mapper XML 未执行XML 不在 classpath 中把 XML 移到resources/mapper/下配置mybatis.mapper-locations端口被占用本机已有进程占用 8080换 port 或杀进程见上文命令druid 相关配置不生效引入了 druid 但没引druid-spring-boot-starter替换或补充依赖JSP 页面 500缺少tomcat-embed-jasper或jstl依赖补依赖确认版本与javax/jakarta对应配置文件不生效配置文件不在src/main/resources/下移动位置或配置resourcesjar 包执行报 “no main manifest attribute”缺spring-boot-maven-plugin在build中补插件UnsupportedClassVersionError编译 JDK 与运行 JDK 不一致统一本地和服务器 JDK 版本5. 改造后的收尾体验几个我反复用的小技巧改造完成不等于彻底结束有几件事我建议你在收尾阶段顺手做掉它们能明显提升后续使用体验。第一个是控制台输出。Spring Boot 默认启动时会打印一个 ASCII 风格的 banner很多人觉得好看但如果你只是为了看日志它可以完全关掉。在application.yml里配置spring: main: banner-mode: off或者更彻底一点把 banner 放在src/main/resources/banner.txt里自定义——网上有在线 banner 生成器随便输入几个字母公司项目里写上项目名个人项目里写个搞笑的句子每天启动时看一眼还挺提神。第二个是热部署。在pom.xml里加一个开发期依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId scoperuntime/scope optionaltrue/optional /dependency加上后IDEA 中修改代码后 CtrlF9Build ProjectSpring Boot 应用会自动重启省去手动 kill 再 start 的时间成本。但注意一点打生产 jar 包时记得保证这个依赖不会被打进去。scoperuntime/scope加上mvn package时它会出现在依赖列表里实际执行java -jar时如果不需要可以加 JVM 参数-Dspring.devtools.restart.enabledfalse关闭。更干净的做法是把 devtools 排除出生产包这个在spring-boot-maven-plugin里用excludeDevtoolstrue/excludeDevtools即可。第三件事是配置多环境。这是传统 Maven 项目改造后体验提升最明显的一点。以前搞多环境靠的是 Maven profile 里配一堆properties然后 filter 替换麻烦不说还容易出错。Spring Boot 原生支持用文件名后缀区分环境application-dev.yml application-prod.yml然后在application.yml里指定激活哪个spring: profiles: active: dev这样不同环境的数据库连接、日志级别、服务端口就能干净地分离。我在实际项目里会把没加active的application.yml作为兜底默认配置这样本地直接启动不会因为缺少配置而崩掉。最后说一个我的个人习惯改造完成后在 Git 里单独开一个分支提交commit 信息写清楚每一步做了什么。这个习惯帮我解决过不少问题——有一次改造到一半发现后续需求迭代需要旧版本的代码支撑直接切回旧分支就行不需要回滚一堆文件。改造这种事做完不是重点做得可控才是重点。如果你手里也有一个跑了好几年的 Maven 老项目我的建议很简单别犹豫改吧。这个改造不会让你的业务代码一夜间焕然一新但它会让你的日常开发和项目维护顺畅一个台阶。既然迟早要做趁项目还处于功能稳定期动手成本最低。