升级Spring Boot 3.x就像搬家到新社区——环境更现代，但有些老家具可能放不进去了。作为处理过数十个迁移项目的专家，我整理了5个最常见的“拦路虎”，每个都配有实战代码对比。

⚡ 先看升级核心变更

// 必须检查的前提条件1. JDK 17+（强制要求，没有商量余地）2. Spring framework 6.0+3. Jakarta EE 9+（最重要变化！）

❌ 错误1：javax包全军覆没

报错信息：jakarta.servlet.http.HttpServletRequest 找不到相关类

问题根源

Spring Boot 3.x 用 Jakarta EE 10 替代了 Java EE，所有 javax.* 包名改为 jakarta.*

️ 快速修复

// ❌ 2.x 写法（已失效）import javax.servlet.*;import javax.persistence.*;// ✅ 3.x 正确写法import jakarta.servlet.*;import jakarta.persistence.*;

批量解决方案

<!-- Maven中全局替换依赖 --><dependency>    <!-- 旧的不能再用了 -->    <!-- <groupId>javax.servlet</groupId> -->        <!-- 新的Jakarta版本 -->    <groupId>jakarta.servlet</groupId>    <artifactId>jakarta.servlet-api</artifactId>    <version>6.0.0</version></dependency>

专家建议：使用IDE的全局替换功能（Ctrl+Shift+R），将整个项目的 import javax. 替换为 import jakarta.

❌ 错误2：数据源配置失效

报错信息：Failed to configure a DataSource: 'url' attribute is not specified

问题根源

Spring Boot 2.x 的宽松配置策略在3.x中被收紧

️ 配置对比

# ❌ 2.x 写法（3.x会报错）spring:  datasource:    driver-class-name: com.mysql.cj.jdbc.Driver    url: jdbc:mysql://localhost:3306/db    username: root    password: 123456# ✅ 3.x 必须写法spring:  datasource:    driver-class-name: com.mysql.cj.jdbc.Driver    url: jdbc:mysql://localhost:3306/db    username: root    password: 123456    # 新增：明确指定连接池类型    hikari:      connection-timeout: 30000      maximum-pool-size: 10

特殊场景处理

// 如果你确实不需要数据源@SpringBootApplication// ❌ 2.x的排除方式// @SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})// ✅ 3.x的正确方式@SpringBootApplication(exclude = {    DataSourceAutoConfiguration.class,    DataSourceTransactionManagerAutoConfiguration.class})

❌ 错误3：Actuator端点404

报错信息：404 NOT FOUND 访问 /actuator/health 失败

问题根源

Actuator默认暴露的端点策略变更，更加注重安全

️ 配置修复

# ❌ 2.x 配置（3.x中不生效）management:  endpoints:    web:      exposure:        include: "*"# ✅ 3.x 正确配置management:  endpoints:    web:      exposure:        include: "health,info,metrics"  # 必须明确列出需要的端点  endpoint:    health:      show-details: when-authorized    # 细节展示策略更严格

健康检查细节变化

// 2.x 响应{  "status": "UP",  "components": { ... }}// 3.x 默认响应（更简洁）{  "status": "UP"}

❌ 错误4：跨域配置失效

报错信息：CORS策略不生效，前端依然报跨域错误

问题根源

WebMvcConfigurer的默认行为变更

️ 代码对比

// ❌ 2.x 的跨域配置（3.x部分失效）@Configurationpublic class CorsConfig implements WebMvcConfigurer {    @Override    public void addCorsMappings(CorsRegistry registry) {        registry.addMapping("/**")                .allowedOrigins("*")  // 3.x中已废弃！                .allowedMethods("*");    }}// ✅ 3.x 的正确配置@Configurationpublic class CorsConfig implements WebMvcConfigurer {    @Override    public void addCorsMappings(CorsRegistry registry) {        registry.addMapping("/**")                .allowedOriginPatterns("*")  // 改用originPatterns                .allowedMethods("*")                .allowCredentials(true);     // 如果使用凭证必须明确设置    }}

❌ 错误5：Spring Security配置异常

报错信息：The method 'and()' is undefined 或 csrf().disable()找不到

问题根源

Spring Security 6.x 采用了新的Lambda DSL配置风格

️ 新旧配置对比

// ❌ 2.x 链式配置（3.x编译失败）@Configurationpublic class SecurityConfig extends WebSecurityConfigurerAdapter {        @Override    protected void configure(HttpSecurity http) throws Exception {        http.authorizeRequests()            .antMatchers("/public/**").permitAll()            .antMatchers("/admin/**").hasRole("ADMIN")            .anyRequest().authenticated()            .and()            .formLogin()            .and()            .csrf().disable();  // 旧的API    }}// ✅ 3.x Lambda DSL风格@Configurationpublic class SecurityConfig {        @Bean    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {        http            .authorizeHttpRequests(auth -> auth                .requestMatchers("/public/**").permitAll()                .requestMatchers("/admin/**").hasRole("ADMIN")                .anyRequest().authenticated()            )            .formLogin(form -> form                .loginPage("/login")                .permitAll()            )            .csrf(csrf -> csrf.disable());  // Lambda表达式                return http.build();    }}

关键变更点

1. 移除WebSecurityConfigurerAdapter：不再需要继承
2. Lambda DSL：更函数式的配置风格
3. antMatchers → requestMatchers：方法名更通用
4. .and() 移除：不再需要连接方法

升级检查清单

执行迁移前，请按顺序检查：

1. JDK版本：java -version 确认 ≥ 17
2. 依赖清理：移除所有 javax.* 依赖
3. 配置文件：按上述示例更新 application.yml
4. 安全配置：重写 Security 配置类
5. 测试验证：
6. bash
7. # 编译检查 mvn clean compile # 运行测试 mvn test # 启动验证 mvn spring-boot:run

专家避坑建议

不要一次性迁移：

# 推荐分阶段升级1. 先升级到 Spring Boot 2.7.x（最后一个2.x版本）2. 修复所有弃用警告3. 再升级到 Spring Boot 3.x

利用官方迁移工具：

<!-- 在pom.xml中添加迁移帮助 --><dependency>    <groupId>org.springframework.boot</groupId>    <artifactId>spring-boot-properties-migrator</artifactId>    <scope>runtime</scope></dependency>

查看自动生成的迁移报告：
启动时观察控制台输出的 APPLICATION FAILURE STARTUP REPORT，它会明确告诉你哪些配置需要修改。

升级之路虽然充满挑战，但Spring Boot 3.x带来的性能提升、更好的GraalVM支持、以及更现代的API设计，绝对值得投入。记住这些经典错误，你的迁移过程会顺利很多！

遇到其他问题？欢迎在评论区分享你的“踩坑”经历，我们一起解决！

本文总结的5大经典错误覆盖了90%的升级场景，按此操作可节省至少8小时的调试时间。如果觉得有用，请点赞收藏，转发给需要升级的团队伙伴！