SpringBoot2升级SpringBoot3完整流程及避坑指南

前言

Spring Boot 2 升级到 Spring Boot 3，可千万别觉得只是把 pom.xml 里的版本号改一下就完事了。

这次升级的核心变化，说白了就是一句话：

Spring Boot 2 升 3，本质上是一次 Ja va 17 + Spring Framework 6 + Jakarta EE 的整体迁移。

换句话说，项目不仅要升级 Spring Boot，还得同步搞定 JDK、依赖包、第三方 starter、配置项、包名变化等等一堆兼容问题。

如果你的项目里用了 MyBatis-Plus、MySQL、Redis，那么最容易踩坑的地方主要有三个：

1. MyBatis-Plus starter 需要换成 Spring Boot 3 专用版本；
2. MySQL 驱动坐标发生了变化；
3. 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，并且要求 Ja va 17+。如果从比较老的 Spring Boot 2.x 直接跳到 3.x，很多问题会一起炸出来，很难判断到底是 JDK 的问题、Spring 的问题，还是第三方依赖的问题。

所以比较稳妥的方式是：先把 Spring Boot 2.x 项目升级到 2.7.x，把旧问题解决掉，再进入 Spring Boot 3 的迁移阶段。

二、JDK 必须升级到 17+

Spring Boot 3 最基本的要求就是：

Ja va 17+

如果你还在用 Ja va 8 或 Ja va 11，项目会直接启动失败，甚至编译阶段就过不去。

在升级之前，先检查本地环境：

ja va -version

Ma ven 环境也建议检查一下：

mvn -v

如果 mvn -v 显示的 Ja va 版本不是 17，那很可能你明明本地装了 JDK 17，但 Ma ven 编译时还是用的旧 JDK。

三、最大变化：ja vax 全面迁移到 jakarta

Spring Boot 3 使用 Jakarta EE，很多包名从 ja vax.* 变成了 jakarta.*。

常见变化如下：

ja vax.servlet.*
ja vax.validation.*
ja vax.annotation.*
ja vax.persistence.*

需要改成：

jakarta.servlet.*
jakarta.validation.*
jakarta.annotation.*
jakarta.persistence.*

比如参数校验里常见的写法：

import ja vax.validation.Valid;
import ja vax.validation.constraints.NotBlank;
import ja vax.validation.constraints.NotNull;

要改成：

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;

再比如：

import ja vax.annotation.Resource;

要改成：

import jakarta.annotation.Resource;

当然，如果不想继续用 @Resource，也可以换成 Spring 的：

@Autowired

不过需要注意，@Resource 和 @Autowired 的注入规则并不完全一样。老项目里如果大量使用 @Resource，建议不要一次性全改，先保证项目能跑起来，再逐步优化。

四、MyBatis-Plus 要换 Spring Boot 3 专用 starter

这是升级过程中非常容易翻车的地方。

Spring Boot 2 项目里常见的 MyBatis-Plus 依赖是：

    com.baomidou
    mybatis-plus-boot-starter

到了 Spring Boot 3，应该换成：

    com.baomidou
    mybatis-plus-spring-boot3-starter
    3.5.16

也就是：

mybatis-plus-boot-starter

要换成：

mybatis-plus-spring-boot3-starter

这可不是名字好不好看的问题，而是 Spring Boot 3 底层已经换成 Spring Framework 6 和 Jakarta 体系，旧 starter 很容易出现兼容性问题。

1. 不要重复引入 MyBatis 原生 starter

引入 MyBatis-Plus 后，一般不建议再单独引入 MyBatis 原生 starter，例如：

    org.mybatis.spring.boot
    mybatis-spring-boot-starter

否则可能会出现版本冲突、Mapper 扫描异常、Bean 重复注册等问题。

建议全局检查这些依赖：

mybatis-plus-boot-starter
mybatis-plus-spring-boot3-starter
mybatis-spring-boot-starter
mybatis-spring

MyBatis-Plus 和 MyBatis 原生 starter 混着用，是老项目升级时的经典雷区。

2. 分页插件、多租户、动态表名要注意

如果项目里用了 MyBatis-Plus 的分页插件、多租户插件、动态表名插件等，还要注意 mybatis-plus-jsqlparser。

可以这样配置：

    
        
            com.baomidou
            mybatis-plus-bom
            3.5.16
            pom
            import
        
    


    
        com.baomidou
        mybatis-plus-spring-boot3-starter
    
    
    
        com.baomidou
        mybatis-plus-jsqlparser
    

这样版本交给 BOM 统一管理，后续升级也更方便。

五、MySQL 驱动坐标要改

Spring Boot 2 老项目中，经常能看到这种 MySQL 驱动写法：

    mysql
    mysql-connector-ja va

Spring Boot 3 中建议改成：

    com.mysql
    mysql-connector-j
    runtime

也就是从：

mysql:mysql-connector-ja va

改成：

com.mysql:mysql-connector-j

application.yml 里的数据源配置一般可以继续这样写：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver

driver-class-name 理论上可以省略，因为 Spring Boot 可以自动识别。不过老项目升级时，建议先保留，等项目跑通后再考虑精简配置。

六、Redis 配置前缀变了

Spring Boot 2 里，Redis 配置一般是这样：

spring:
  redis:
    host: localhost
    port: 6379
    password:
    database: 0

Spring Boot 3 里要改成：

spring:
  data:
    redis:
      host: localhost
      port: 6379
      password:
      database: 0

变化点就是：

spring.redis.*

改成：

spring.data.redis.*

如果项目里用了 Lettuce 连接池，Spring Boot 3 下可以这样写：

spring:
  data:
    redis:
      host: localhost
      port: 6379
      database: 0
      lettuce:
        pool:
          max-active: 8
          max-idle: 8
          min-idle: 0
          max-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: ja vax.servlet...	没有把 ja vax.servlet 改成 jakarta.servlet
ClassNotFoundException: ja vax.validation...	没加 spring-boot-starter-validation，或者没改成 jakarta.validation
Invalid value type for attribute 'factoryBeanObjectType': ja va.lang.String	MyBatis / MyBatis-Plus / MyBatis-Spring 版本不兼容
Invalid bound statement not found	Mapper XML 路径、Mapper 扫描路径或 MyBatis-Plus 配置有问题
Failed to configure a DataSource	MySQL 驱动坐标或数据源配置有问题
Redis 配置不生效	还在使用 spring.redis.*
分页插件不生效	MyBatis-Plus 插件配置没迁移，或缺少 mybatis-plus-jsqlparser
启动提示 Bean 重复	MyBatis 和 MyBatis-Plus 依赖重复引入

其中比较典型的是这个错误：

Invalid value type for attribute 'factoryBeanObjectType': ja va.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 配置示例：

    org.springframework.boot
    spring-boot-starter-parent
    3.3.13
    


    17
    3.5.16


    
        
            com.baomidou
            mybatis-plus-bom
            ${mybatis-plus.version}
            pom
            import
        
    


    
    
        org.springframework.boot
        spring-boot-starter-web
    
    
    
        com.baomidou
        mybatis-plus-spring-boot3-starter
    
    
    
        com.baomidou
        mybatis-plus-jsqlparser
    
    
    
        com.mysql
        mysql-connector-j
        runtime
    
    
    
        org.springframework.boot
        spring-boot-starter-data-redis
    
    
    
        org.springframework.boot
        spring-boot-starter-validation
    
    
    
        org.springframework.boot
        spring-boot-starter-test
        test
    

如果项目是从 Spring Boot 2.3.6 升到 Spring Boot 3.2.6，也可以把 parent 版本改成：

3.2.6

不要盲目复制版本号，最好结合项目实际情况和官方兼容表选择。

十、升级前建议全局搜索这些关键词

迁移前，建议直接在项目里全局搜索：

ja vax.
spring.redis
mysql-connector-ja va
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. 确认 Ma ven 版本是否满足要求
3. Spring Boot 2.x 先升级到 2.7.x
4. 解决旧版本中的 deprecated 和 warning
5. Spring Boot parent 改成 3.x
6. 全项目 ja vax.* 改成 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，最核心的不是改版本号，而是处理整个技术栈的兼容性。

可以记住这几个重点：

Ja va 17+
ja vax → jakarta
MyBatis-Plus 换 Boot3 starter
MySQL 驱动换新坐标
Redis 配置前缀改成 spring.data.redis
第三方 starter 必须确认 Boot3 兼容性

如果只改 Spring Boot 版本，不处理这些细节，项目很容易出现启动失败、Bean 初始化失败、Redis 配置不生效、Mapper 找不到、数据库连接失败等问题。

一个稳妥的建议是：不要一次性把所有东西都改完。

升级这种事，最好一层一层来：

先环境
再依赖
再配置
再代码
最后测试

这样遇到问题时，定位会清晰很多，也不容易把自己绕进去。