SpringBoot 2 升级到 3：实战踩坑与完整避坑指南

作者 lucy · 2026-04-17

⚠️ 声明：本文相关内容仅供参考，实际升级请以官方文档为准，谨慎操作。

RuoYi-Vue-Plus 近期宣布全面支持 SpringBoot 3，很多朋友想升级但担心踩坑。本文从实际项目升级经验出发，梳理 SpringBoot 2 升级到 3 的核心变动和常见坑点，供大家参考。

一、为什么 SpringBoot 3 值得升级

JDK 17+ 原生支持：SpringBoot 3 要求 JDK 17+，可直接使用虚拟线程（Virtual Threads），并发处理能力大幅提升
Jakarta EE 9+：从 javax 迁移到 jakarta 命名空间，解除 Oracle 版权限制
GraalVM 原生构建支持：可编译为 Native Image，冷启动仅需毫秒级，适合 Serverless 场景
Spring Framework 6 新特性：更强的配置校验、AOT 运行时增强、REST 客户端统一

二、升级前准备

1. JDK 版本检查

# 检查当前 JDK 版本
java -version

# SpringBoot 3.x 要求 JDK 17+
# 建议使用 Spring Boot 3.2+ 支持 JDK 21
# 下载地址：https://adoptium.net/

2. Maven 版本升级

<!-- pom.xml -->
<properties>
    <java.version>17</java.version>
    <spring-boot.version>3.2.5</spring-boot.version>
    <mybatis-plus.version>3.5.6</mybatis-plus.version>
</properties>

<!-- 父 pom 版本要求 -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.5</version>
</parent>

三、常见踩坑及解决方案

坑一：javax → jakarta 命名空间迁移

SpringBoot 3 全面迁移到 Jakarta EE 9（jakarta.*），旧代码中的 javax.* 全部失效。

# 典型报错
NoClassDefFoundError: javax/servlet/Filter
ClassNotFoundException: javax.persistence.Entity

# 解决：批量替换 import 语句
# IntelliJ IDEA 支持全局替换：
javax.servlet.*  →  jakarta.servlet.*
javax.annotation.* →  jakarta.annotation.*
javax.persistence.* →  jakarta.persistence.*
javax.validation.* →  jakarta.validation.*

<!-- 典型依赖变更 -->
<!-- SpringBoot 2.x -->
<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>4.0.1</version>
</dependency>

<!-- SpringBoot 3.x -->
<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.0.0</version>
</dependency>

坑二：MyBatis-Plus 版本不兼容

RuoYi-Vue-Plus 使用 MyBatis-Plus，升级 SpringBoot 3 后必须同步升级 MP 版本。

<!-- MyBatis-Plus 版本要求 -->
<!-- SpringBoot 3 + JDK 17 需要 MP 3.5.4 及以上 -->
<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.5.6</version>
</dependency>

# 典型报错
Caused by: java.lang.NoClassDefFoundError: org/mybatis/logging/Logger

# 原因：旧版 MP 不支持 SpringBoot 3 的类加载器
# 解决：升级到 MP 3.5.5+

坑三：数据库连接池配置变更

HikariCP 在 SpringBoot 3 中配置项前缀变了，部分旧配置失效。

# SpringBoot 2.x 配置（仍然有效，但建议更新）
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      minimum-idle: 10
      maximum-pool-size: 20
      idle-timeout: 30000
      max-lifetime: 1800000
      connection-timeout: 30000

# SpringBoot 3 建议新增的配置
spring:
  datasource:
    hikari:
      pool-name: HikariPool-Master
      register-mbeans: true  # 开启 JMX 注册，方便监控

# 验证连接池是否正常工作
# 启动后访问 /actuator/health 查看
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,prometheus
  endpoint:
    health:
      show-details: always

坑四：配置文件路径问题

SpringBoot 3 加强了配置校验，部分旧配置项名称变化或被移除。

# 典型失效配置
# SpringBoot 2.x
server.compression.enabled=true
server.compression.mime-types=text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json

# SpringBoot 3 推荐写法（基本不变，但需注意校验）
server:
  compression:
    enabled: true
    mime-types: text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json

坑五：Security 配置不兼容

Spring Security 6 取消了部分旧写法，WebSecurityConfigurerAdapter 已移除。

// SpringBoot 2.x（旧写法，已废弃）
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests().anyRequest().authenticated();
    }
}

// SpringBoot 3.x（新版写法）
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(AbstractHttpConfigurer::disable)
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/admin/**").authenticated()
                .anyRequest().permitAll()
            );
        return http.build();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

四、升级检查清单

☐ JDK 版本升级到 17+（建议 JDK 21）
☐ SpringBoot 版本升级到 3.2.x
☐ MyBatis-Plus 升级到 3.5.6+
☐ 批量替换 javax.* → jakarta.*
☐ 更新所有依赖到兼容 SpringBoot 3 的版本
☐ 更新 Spring Security 配置（去除 WebSecurityConfigurerAdapter）
☐ 配置类添加 @ConfigurationProperties 校验
☐ 启动测试，检查 actuator /health 状态
☐ 全量接口回归测试
☐ 压测对比升级前后性能（TPS、响应时间）

五、实战建议

不要跳跃式升级：建议 SpringBoot 2.7 → 3.0 → 3.1 → 3.2 逐步推进，每次小版本验证后再升级
建立基线：升级前先跑一轮接口性能测试，记录 TPS 和响应时间 P99，升级后做对比
保留回滚方案：数据库加版本标识，接口字段变更做好兼容
关注第三方依赖：Druid、ShardingJDBC、分布式事务组件等均需确认是否支持 SpringBoot 3

⚠️ 再声明：升级操作涉及项目核心依赖，请在测试环境充分验证后再上生产，做好代码备份和回滚预案，不同框架版本组合可能遇到其他兼容性问题。

有问题欢迎留言交流 🚀