当前位置:

首页 > 编程开发 > SpringBoot2升级SpringBoot3完整流程及避坑指南

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

SpringBoot2升3需JDK17及SpringFramework6,javax包名改为jakarta。MyBatis-Plus需专用starter,MySQL驱动坐标变化,Redis配置前缀改为spring.data.redis.*。建议先升级至2.7.x再迁移。

本文目录

    前言

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

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

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

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

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

    升级这种事,最好一层一层来:

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

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

    本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系bd@zhengruan.com
    作者最新文章
    编程开发 避坑指南
    相关文章 更多
    2026年7月4000元档拍照手机怎么选 从入门到旗舰的影像阶梯与避坑指南
    2026年7月4000元档拍照手机怎么选 从入门到旗舰的影像阶梯与避坑指南

    2026年7月,4000元档拍照手机进入拼底、拼算法、拼续航阶段。主摄与长焦双大底是关键,vivoX300s采用1/1.4英寸主摄加1/1.95英寸APO长焦,搭载蓝图影像芯片V3+和7100mAh电池,国补后约4499元,是综合影像体验较完整的机型。选购需关注传感器实际尺寸,避免盲目追首发。

    果蔬清洗机十大品牌实测,2026年选购避坑指南
    果蔬清洗机十大品牌实测,2026年选购避坑指南

    基于权威检测与用户调研,从技术成熟度、净化效率、用户体验、售后等维度评测十大果蔬清洗机品牌。指出羟基水离子技术优势,提醒关注第三方检测报告、材料安全与售后服务,避免选购陷阱。

    2026 新房除甲醛常见误区盘点 6款靠谱除醛产品选购避坑指南
    2026 新房除甲醛常见误区盘点 6款靠谱除醛产品选购避坑指南

    新房除醛存在依赖通风绿植、盲目相信“一次治理”等误区。靠谱产品需具备清晰技术原理、权威检测报告与客观表述。六款测评产品中,纳蕴石和蕴岛无光分解喷雾因无光催化分解技术、资质齐全表现突出,搭配喷雾与炭包并配合通风可有效降低甲醛。

    Git之常用命令与避坑指南分享
    Git之常用命令与避坑指南分享

    一、Git 基础配置 在用Git之前,有两件事最好先搞定,否则后续操作会处处碰壁。 # 设置全局用户信息(必填,否则无法提交) git config --global user.name "你的用户名" git config --global user.email "你的邮箱@example.com

    Java中单引号和双引号的区别是什么?新手必看避坑指南
    Java中单引号和双引号的区别是什么?新手必看避坑指南

    Java中单引号表示字符类型char,只能包含一个字符;双引号表示字符串类型String,可包含零或多个字符。字符可直接转为字符串,字符串需用charAt()获取字符。判断空格时使用单引号包裹空格字符即可。

    2000元档洗衣机避坑指南:认准12kg大容量与直驱电机
    2000元档洗衣机避坑指南:认准12kg大容量与直驱电机

    在洗衣机市场里,2000元这个价位段,其实是个挺有意思的“分水岭”。到了这个预算,意味着你已经不满足于“能把衣服洗个大概”就行,而是开始琢磨:洗得是不是更干净、噪音能不能小点、容量能不能一次搞定全家一周的换洗。对于大多数普通家庭来说,这个档位做决策,最忌讳的就是被那些花里胡哨、一年用不了几次的功能牵

    2026作业辅导学习机避坑指南:对比一圈才懂,全链路 AI 作业辅导闭环真有用
    2026作业辅导学习机避坑指南:对比一圈才懂,全链路 AI 作业辅导闭环真有用

    对比多款学习机后发现,全链路AI作业辅导闭环至关重要,需覆盖作业规划、答疑、批改、错题提升及复习备考,避免单点搜题功能。步步高学习机具备启发式讲解、精准批改及母题溯源体系,能有效解决作业辅导难题。

    保密观APP避坑指南:3个新手容易忽略的学习误区【教程】
    保密观APP避坑指南:3个新手容易忽略的学习误区【教程】

    保密观APP学习考试中,常见三个误区:只刷课不答题导致学时无效;未绑定单位使学分不累计;交卷前未确认全部作答导致成绩作废。避开这些操作习惯错误,可有效提高通过率。

    光环游戏助手云存档避坑指南:数据备份与跨设备恢复【详解】
    光环游戏助手云存档避坑指南:数据备份与跨设备恢复【详解】

    光环助手云存档是游戏数据备份与跨设备恢复的关键途径。上传前须退出游戏、登录账号并确保游戏支持。提供悬浮窗和详情页两种上传方式。恢复时需登录同一账号下载覆盖存档。上传后应验证存档大小及时间以确保有效。

    光环游戏助手安装失败避坑指南:未知来源权限与兼容性解决【详解】
    光环游戏助手安装失败避坑指南:未知来源权限与兼容性解决【详解】

    光环游戏助手安装失败主因:系统权限未开启、安卓14底层拦截及CPU架构不匹配。解决:开启未知来源安装权限,通过官网扫码直装绕过拦截,并选择ARM64-v8a专用包避免闪退。建议确保上述步骤后重试。

    查看更多
    精品专题 更多
    装机必备
    装机必备

    正软商城装机必备专区,精选办公、浏览器、安全防护、影音播放、压缩解压、设计创作和系统工具等电脑常用正版软件,帮助用户快速完成新电脑软件配置。

    Windows
    Windows

    正软商城Windows软件专区,汇集适用于Windows电脑的办公、设计、安全防护、影音播放、开发工具和系统优化软件,提供软件介绍、系统要求、正版授权及购买下载服务。

    PDF教程
    PDF教程

    正软商城PDF教程频道提供PDF编辑、转换、合并、拆分、压缩及格式处理方法,同时介绍常用PDF软件和工具的使用技巧。

    Mac软件 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    Aperty macOS版
    Aperty macOS版
    macOS

    Aperty 是 Skylum 推出的 AI 人像修图软件,支持自然肤质修饰、瑕疵处理、面部与身体调整、预设及批量同步。

    WINDOWS 更多
    讯飞智作 网页版
    讯飞智作 网页版
    Windows/ macOS/ Linux

    讯飞智作是一款基于语音合成技术、虚拟人驱动技术与数字人形象声音构建能力的 AI 数字人音视频创作平台。

    火山引擎 网页版
    火山引擎 网页版
    Windows/ macOS/ Linux

    火山引擎是字节跳动旗下企业级云与AI服务平台。聚焦大模型核心能力,依托字节自研豆包多模态大模型,凭借火山方舟一站式平台,提供模型精调、推理部署、智能应用搭建等全链路服务,结合高性能AI算力,助力各行业快速落地大模型数字化与智能化应用。

    PixTV 网页版
    PixTV 网页版
    Windows

    PixTV 是一款在浏览器中使用的 AI 视觉内容创作平台,提供图片、视频、音频、文字生成、AI 分镜、局部重绘、提示词反推和无限画布等工具,适合短剧、漫剧、广告及社交媒体内容制作。