Spring Boot 2 升级 Spring Boot 3 踩坑实战MyBatis-Plus、MySQL、Redis 迁移总结前言Spring Boot 2 升级到 Spring Boot 3千万不要以为只是把pom.xml里的版本号改一下这么简单。这次升级的核心变化可以概括成一句话Spring Boot 2 升 3本质上是 Java 17 Spring Framework 6 Jakarta EE 的一次整体迁移。也就是说项目不仅要升级 Spring Boot还要同步处理 JDK、依赖包、第三方 starter、配置项、包名变化等一堆兼容问题。如果你的项目里用了MyBatis-Plus、MySQL、Redis那么最容易踩坑的地方主要有三个MyBatis-Plus starter 需要换成 Spring Boot 3 专用版本MySQL 驱动坐标发生变化Redis 配置前缀从spring.redis.*改成了spring.data.redis.*。下面就按实际升级流程把需要注意的地方完整梳理一遍。一、不要直接从 Spring Boot 2.x 跳到 Spring Boot 3如果项目还停留在 Spring Boot 2.3、2.4、2.5 这种比较老的版本建议不要直接硬升到 Spring Boot 3。更稳的升级路线是Spring Boot 2.x ↓ 先升级到 Spring Boot 2.7.x 最新版 ↓ 解决 deprecated、warning 和兼容问题 ↓ JDK 升级到 17 ↓ 再升级到 Spring Boot 3.x为什么要这样做因为 Spring Boot 3 的底层是 Spring Framework 6并且要求 Java 17。如果你从比较老的 Spring Boot 2.x 直接跳到 3.x很多问题会一起爆出来很难判断到底是 JDK 问题、Spring 问题还是第三方依赖问题。所以比较稳妥的方式是先把 Spring Boot 2.x 项目升级到 2.7.x把旧问题解决掉再进入 Spring Boot 3 的迁移阶段。二、JDK 必须升级到 17Spring Boot 3 最基本的要求就是Java 17如果你还在用 Java 8 或 Java 11项目会直接启动失败甚至编译阶段就过不去。在升级之前先检查本地环境java-versionMaven 环境也建议检查一下mvn-v如果mvn -v显示的 Java 版本不是 17也可能导致你明明本地装了 JDK 17但 Maven 编译时还是用旧 JDK。三、最大变化javax 全面迁移到 jakartaSpring Boot 3 使用 Jakarta EE很多包名从javax.*变成了jakarta.*。常见变化如下javax.servlet.* javax.validation.* javax.annotation.* javax.persistence.*需要改成jakarta.servlet.* jakarta.validation.* jakarta.annotation.* jakarta.persistence.*比如参数校验里常见的写法importjavax.validation.Valid;importjavax.validation.constraints.NotBlank;importjavax.validation.constraints.NotNull;要改成importjakarta.validation.Valid;importjakarta.validation.constraints.NotBlank;importjakarta.validation.constraints.NotNull;再比如importjavax.annotation.Resource;要改成importjakarta.annotation.Resource;当然如果你不想继续用Resource也可以改成 Spring 的Autowired不过需要注意Resource和Autowired的注入规则并不完全一样。老项目里如果大量使用Resource建议不要一次性全改先保证项目能跑起来再逐步优化。四、MyBatis-Plus 要换 Spring Boot 3 专用 starter这是升级过程中非常容易炸的地方。Spring Boot 2 项目里常见的 MyBatis-Plus 依赖是dependencygroupIdcom.baomidou/groupIdartifactIdmybatis-plus-boot-starter/artifactId/dependency到了 Spring Boot 3应该换成dependencygroupIdcom.baomidou/groupIdartifactIdmybatis-plus-spring-boot3-starter/artifactIdversion3.5.16/version/dependency也就是说mybatis-plus-boot-starter要换成mybatis-plus-spring-boot3-starter这个不是名字好不好看的问题而是 Spring Boot 3 底层已经换成 Spring Framework 6 和 Jakarta 体系旧 starter 很容易出现兼容性问题。1. 不要重复引入 MyBatis 原生 starter引入 MyBatis-Plus 后一般不要再单独引入 MyBatis 原生 starter例如dependencygroupIdorg.mybatis.spring.boot/groupIdartifactIdmybatis-spring-boot-starter/artifactId/dependency否则可能会出现版本冲突、Mapper 扫描异常、Bean 重复注册等问题。建议全局检查这些依赖mybatis-plus-boot-starter mybatis-plus-spring-boot3-starter mybatis-spring-boot-starter mybatis-springMyBatis-Plus 和 MyBatis 原生 starter 混着用属于老项目升级时的经典雷区。2. 分页插件、多租户、动态表名要注意如果项目里用了 MyBatis-Plus 的分页插件、多租户插件、动态表名插件等还要注意mybatis-plus-jsqlparser。可以这样配置dependencyManagementdependenciesdependencygroupIdcom.baomidou/groupIdartifactIdmybatis-plus-bom/artifactIdversion3.5.16/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagementdependenciesdependencygroupIdcom.baomidou/groupIdartifactIdmybatis-plus-spring-boot3-starter/artifactId/dependency!-- 如果用了分页、多租户、动态表名等插件建议加上 --dependencygroupIdcom.baomidou/groupIdartifactIdmybatis-plus-jsqlparser/artifactId/dependency/dependencies这样版本交给 BOM 统一管理后续升级也更方便。五、MySQL 驱动坐标要改Spring Boot 2 老项目中经常能看到这种 MySQL 驱动写法dependencygroupIdmysql/groupIdartifactIdmysql-connector-java/artifactId/dependencySpring Boot 3 中建议改成dependencygroupIdcom.mysql/groupIdartifactIdmysql-connector-j/artifactIdscoperuntime/scope/dependency也就是从mysql:mysql-connector-java改成com.mysql:mysql-connector-japplication.yml里的数据源配置一般可以继续这样写spring:datasource:url:jdbc:mysql://localhost:3306/demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghaiusername:rootpassword:rootdriver-class-name:com.mysql.cj.jdbc.Driverdriver-class-name理论上可以省略因为 Spring Boot 可以自动识别。但老项目升级时我建议先保留等项目跑通后再考虑精简配置。六、Redis 配置前缀变了Spring Boot 2 里Redis 配置一般是这样spring:redis:host:localhostport:6379password:database:0Spring Boot 3 里要改成spring:data:redis:host:localhostport:6379password:database:0变化点就是spring.redis.*改成spring.data.redis.*如果你项目里用了 Lettuce 连接池Spring Boot 3 下可以这样写spring:data:redis:host:localhostport:6379database:0lettuce:pool:max-active:8max-idle:8min-idle:0max-wait:1000ms升级后如果你发现 Redis 配置不生效先别急着怀疑 Redis 服务优先检查是不是还在用旧的spring.redis.*。七、Redis 序列化不要随便改Redis 配置前缀需要改但 Redis 序列化方式不要随便改。很多老项目里 Redis 存的数据可能是JDK 原生序列化 FastJson 序列化 Jackson JSON 序列化 带 class 类型信息的 JSON 自定义序列化格式如果升级 Spring Boot 3 的时候顺手把 RedisTemplate 的序列化器也改了可能会出现这些问题反序列化失败 缓存读取失败 登录态失效 验证码失效 Session 全部掉线所以我的建议是第一阶段只升级 Spring Boot 和依赖RedisTemplate 序列化方式先保持不变。 第二阶段等项目稳定运行后再考虑统一 Redis 序列化方案。如果 Redis 里只是普通缓存清掉问题不大。但如果 Redis 里存的是登录态、验证码、订单临时状态、限流数据就千万别莽。八、常见报错和对应原因升级 Spring Boot 3 的过程中可以根据报错快速定位问题。报错大概率原因ClassNotFoundException: javax.servlet...没有把javax.servlet改成jakarta.servletClassNotFoundException: javax.validation...没加spring-boot-starter-validation或者没改成jakarta.validationInvalid value type for attribute factoryBeanObjectType: java.lang.StringMyBatis / MyBatis-Plus / MyBatis-Spring 版本不兼容Invalid bound statement not foundMapper XML 路径、Mapper 扫描路径或 MyBatis-Plus 配置有问题Failed to configure a DataSourceMySQL 驱动坐标或数据源配置有问题Redis 配置不生效还在使用spring.redis.*分页插件不生效MyBatis-Plus 插件配置没迁移或缺少mybatis-plus-jsqlparser启动提示 Bean 重复MyBatis 和 MyBatis-Plus 依赖重复引入其中比较典型的是这个错误Invalid value type for attribute factoryBeanObjectType: java.lang.String这个错误经常出现在 Spring Boot 3.2.x 项目里根本原因通常是旧版本 MyBatis、MyBatis-Spring 或 MyBatis-Plus 与 Spring Framework 6.1 不兼容。解决方向不是乱改业务代码而是先检查依赖mybatis-plus-boot-starter mybatis-plus-spring-boot3-starter mybatis-spring-boot-starter mybatis-spring确保使用 Spring Boot 3 兼容版本并删除重复依赖。九、推荐 pom.xml 结构下面是一个比较常见的 Spring Boot 3 MyBatis-Plus MySQL Redis 的 pom 配置示例parentgroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-parent/artifactIdversion3.3.13/versionrelativePath//parentpropertiesjava.version17/java.versionmybatis-plus.version3.5.16/mybatis-plus.version/propertiesdependencyManagementdependenciesdependencygroupIdcom.baomidou/groupIdartifactIdmybatis-plus-bom/artifactIdversion${mybatis-plus.version}/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagementdependencies!-- Web --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- MyBatis-Plus for Spring Boot 3 --dependencygroupIdcom.baomidou/groupIdartifactIdmybatis-plus-spring-boot3-starter/artifactId/dependency!-- 如果用了分页、多租户、动态表名等插件建议加上 --dependencygroupIdcom.baomidou/groupIdartifactIdmybatis-plus-jsqlparser/artifactId/dependency!-- MySQL 驱动 --dependencygroupIdcom.mysql/groupIdartifactIdmysql-connector-j/artifactIdscoperuntime/scope/dependency!-- Redis --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-data-redis/artifactId/dependency!-- 参数校验如果用了 Valid / NotBlank / NotNull需要加 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-validation/artifactId/dependency!-- 测试 --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-test/artifactIdscopetest/scope/dependency/dependencies如果你项目是从 Spring Boot 2.3.6 升到 Spring Boot 3.2.6也可以把 parent 版本改成version3.2.6/version不要盲目复制版本号最好结合项目实际情况和官方兼容表选择。十、升级前建议全局搜索这些关键词迁移前建议直接在项目里全局搜索javax. spring.redis mysql-connector-java mybatis-plus-boot-starter mybatis-spring-boot-starter mybatis-spring如果项目里有 Swagger、Spring Security、Knife4j还要继续搜springfox swagger knife4j WebSecurityConfigurerAdapter因为 Spring Boot 3 对 Spring Security、Swagger 这类生态依赖的影响也很大。例如Spring Security 5 → Spring Security 6 Springfox → springdoc-openapi 2.x 旧版 Knife4j → Boot3 兼容版本这些不一定每个项目都会遇到但只要项目里用了就要单独处理。十一、我的升级检查清单最后整理一份升级检查清单按这个顺序排查会比较稳1. 确认 JDK 是否为 17 2. 确认 Maven 版本是否满足要求 3. Spring Boot 2.x 先升级到 2.7.x 4. 解决旧版本中的 deprecated 和 warning 5. Spring Boot parent 改成 3.x 6. 全项目 javax.* 改成 jakarta.* 7. MyBatis-Plus starter 换成 mybatis-plus-spring-boot3-starter 8. 删除重复的 mybatis-spring-boot-starter 9. MySQL 驱动改成 com.mysql:mysql-connector-j 10. Redis 配置从 spring.redis 改成 spring.data.redis 11. RedisTemplate 序列化方式先不要乱改 12. 检查 Mapper XML 路径和 MapperScan 配置 13. 如果使用分页插件检查 mybatis-plus-jsqlparser 14. 如果使用 Spring Security单独迁移 Security 6 15. 如果使用 Swagger优先考虑 springdoc-openapi 2.x 16. 最后进行完整回归测试总结Spring Boot 2 升级到 Spring Boot 3最核心的不是改版本号而是处理整个技术栈的兼容性。可以记住这几个重点Java 17 javax → jakarta MyBatis-Plus 换 Boot3 starter MySQL 驱动换新坐标 Redis 配置前缀改成 spring.data.redis 第三方 starter 必须确认 Boot3 兼容性如果只改 Spring Boot 版本不处理这些细节项目很容易出现启动失败、Bean 初始化失败、Redis 配置不生效、Mapper 找不到、数据库连接失败等问题。我的建议是不要一次性把所有东西都改完。升级这种事最好一层一层来先环境 再依赖 再配置 再代码 最后测试这样遇到问题时定位会清晰很多也不容易把自己绕进去。参考资料[1] Spring Boot 3.0 Migration Guidehttps://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.0-Migration-Guide[2] MyBatis-Plus Installationhttps://baomidou.com/en/getting-started/install/[3] MySQL Connector/J Maven 安装文档https://dev.mysql.com/doc/connector-j/en/connector-j-installing-maven.html[4] Spring Data Redis Drivershttps://docs.spring.io/spring-data/redis/reference/redis/drivers.html