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

更新时间：2026年07月01日 09:13:02 作者：cyforkk

SpringBoot从2升级到3,不只是改版本号,需要处理JDK、依赖、配置等兼容问题,重点包括JDK升级到17、MyBatis-PlusSpringBoot3专用starter、MySQL驱动坐标变化、Redis配置前缀改为spring.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 必须升级到 17+

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

Java 17+

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

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

java -version

Maven 环境也建议检查一下：

mvn -v

如果 mvn -v 显示的 Java 版本不是 17，也可能导致你明明本地装了 JDK 17，但 Maven 编译时还是用旧 JDK。

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

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

常见变化如下：

javax.servlet.*
javax.validation.*
javax.annotation.*
javax.persistence.*

需要改成：

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

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

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

要改成：

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

再比如：

import javax.annotation.Resource;

要改成：

import jakarta.annotation.Resource;

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

@Autowired

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

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

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

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

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
</dependency>

到了 Spring Boot 3，应该换成：

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.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，例如：

<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
</dependency>

否则可能会出现版本冲突、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。

可以这样配置：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-bom</artifactId>
            <version>3.5.16</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    </dependency>
    <!-- 如果用了分页、多租户、动态表名等插件，建议加上 -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-jsqlparser</artifactId>
    </dependency>
</dependencies>

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

五、MySQL 驱动坐标要改

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

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
</dependency>

Spring Boot 3 中建议改成：

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

也就是从：

mysql:mysql-connector-java

改成：

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: javax.servlet...`	没有把 `javax.servlet` 改成 `jakarta.servlet`
`ClassNotFoundException: javax.validation...`	没加 `spring-boot-starter-validation`，或者没改成 `jakarta.validation`
`Invalid value type for attribute 'factoryBeanObjectType': java.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': 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 配置示例：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.13</version>
    <relativePath/>
</parent>
<properties>
    <java.version>17</java.version>
    <mybatis-plus.version>3.5.16</mybatis-plus.version>
</properties>
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-bom</artifactId>
            <version>${mybatis-plus.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <!-- Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- MyBatis-Plus for Spring Boot 3 -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    </dependency>
    <!-- 如果用了分页、多租户、动态表名等插件，建议加上 -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-jsqlparser</artifactId>
    </dependency>
    <!-- MySQL 驱动 -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>
    <!-- Redis -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-redis</artifactId>
    </dependency>
    <!-- 参数校验：如果用了 @Valid / @NotBlank / @NotNull，需要加 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <!-- 测试 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

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

<version>3.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 找不到、数据库连接失败等问题。

我的建议是：不要一次性把所有东西都改完。
升级这种事，最好一层一层来：

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

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

以上就是SpringBoot2升级SpringBoot3完整流程及避坑指南的详细内容，更多关于SpringBoot2升级SpringBoot3流程的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:

浅谈Java线程池完全指南
Java线程池通过复用线程减少创建销毁开销,控制并发数防止资源耗尽,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
2026-06-06
解决springboot+shiro 权限拦截失效的问题
这篇文章主要介绍了解决springboot+shiro 权限拦截失效的问题，具有很好的参考价值，希望对大家有所帮助。一起跟随小编过来看看吧
2020-09-09
Spring Security 过滤器注册脉络梳理
这篇文章主要介绍了Spring Security过滤器注册脉络梳理,Spring Security在Servlet的过滤链中注册了一个过滤器FilterChainProxy，它会把请求代理到Spring Security自己维护的多个过滤链，每个过滤链会匹配一些URL，如果匹配则执行对应的过滤器
2022-08-08
动态上传jar包热部署的实战详解
开发系统过程中遇到的一个需求，系统给定一个接口，用户可以自定义开发该接口的实现，并将实现打成jar包，上传到系统中。系统完成热部署，并切换该接口的实现。本文详细介绍了实现方法，需要的可以参考一下
2022-10-10
玩转spring boot 快速开始（1）
玩转spring boot，快速开始spring boot学习，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
2017-01-01
MyBatis实现分页全过程
MyBatis分页有三种方式：手动SQL分页（性能高但需处理数据库差异）、RowBounds（简单但不推荐）、PageHelper分页插件（自动改写SQL,推荐生产环境）,PageHelper适合百万级数据优化,是终极解决方案
2025-08-08
Java工具之ja-netfilter 2022.1 配置教程
这篇文章主要介绍了Java工具之ja-netfilter 2022.1 配置教程,本防火墙基于javaagent，所以目前只有基于java的程序能够使用，需要的朋友可以参考下
2022-04-04
分布式面试分布式锁实现及应用场景
这篇文章主要为大家介绍了关于分布式的面试问题，分布式锁的实现及应用不同场景下的使用，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步
2022-03-03
maven的pom.xml中repositories和distributionManagement使用
这篇文章主要介绍了maven的pom.xml中repositories和distributionManagement使用方式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2024-03-03
Java中的List接口实现类解析
这篇文章主要介绍了Java中的List接口实现类解析，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2022-02-02