mokee网关云

Spring Boot 2 迁移到 Spring Boot 3 实战指南

📅

✍️

mokee

为什么要迁移？

Spring Boot 2.x 已于 2023 年 11 月停止维护（EOL），迁移到 Spring Boot 3.x 不仅是追随技术趋势，更是为了获得安全补丁和性能提升。

迁移前检查清单

  1. JDK 版本：确保已升级到 JDK 17+
  2. 依赖兼容性：检查所有第三方库是否支持 Jakarta EE
  3. IDE 版本：IntelliJ IDEA 2022.1+ / Eclipse 2022-03+
  4. 构建工具：Maven 3.5+ / Gradle 7.5+

分步迁移指南

步骤 1：升级 Spring Boot 版本

<!-- pom.xml -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.0</version>
</parent>

<properties>
    <java.version>17</java.version>
</properties>

步骤 2：迁移 javax.* 到 jakarta.*

全局搜索替换 javax.persistence → jakarta.persistence，javax.servlet → jakarta.servlet 等。也可以使用 OpenRewrite 工具自动迁移：

# 使用 Maven 插件自动迁移
./mvnw org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-migrate-java:LATEST \
  -DactiveRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta

步骤 3：升级安全配置

// Spring Boot 2.x 写法（已废弃）
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/public/**").permitAll()
            .anyRequest().authenticated();
    }
}

// Spring Boot 3.x 新写法（Lambda DSL）
@Configuration
@EnableWebSecurity
public class SecurityConfig {
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
            .requestMatchers("/public/**").permitAll()
            .anyRequest().authenticated()
        );
        return http.build();
    }
}

步骤 4：更新 Actuator 端点

# Spring Boot 3 废除了某些旧属性
# management.endpoints.web.base-path 默认仍为 /actuator
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
  endpoint:
    health:
      show-details: always

步骤 5：处理日期时间序列化

# Spring Boot 3 默认不再将 Date 序列化为时间戳
# 如需保持旧行为：
spring:
  jackson:
    serialization:
      write-dates-as-timestamps: true

常见问题与解决方案

Q1：MyBatis Plus 不兼容

升级到 MyBatis Plus 3.5.3.1+ 版本，该版本已完全支持 Jakarta EE 和 Spring Boot 3。

Q2：Swagger/SpringFox 无法使用

SpringFox 已停更，建议迁移到 SpringDoc OpenAPI：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

Q3：Hibernate 6 的变更

  • Hibernate 6 默认使用更严格的序列生成策略
  • @Type 注解的类型定义方式有变化
  • HQL 查询语法更加严格

Q4：Traefik / Nginx 代理配置

如果使用 X-Forwarded-* 头，确保配置：

server:
  forward-headers-strategy: framework

迁移验证清单

  1. ✅ 编译无错误
  2. ✅ 单元测试通过
  3. ✅ 集成测试通过
  4. ✅ 健康检查端点正常响应
  5. ✅ 数据库连接和 ORM 操作正常
  6. ✅ 安全认证流程正常
  7. ✅ 日志输出格式正确
  8. ✅ 监控指标正常上报

总结

从 Spring Boot 2 升级到 3 的迁移工作主要集中在 Jakarta EE 包名替换和废弃 API 适配上。使用 OpenRewrite 等自动化工具可以大幅减少手工修改的工作量。建议在迁移前做好充分的测试覆盖，确保业务功能的稳定性。

标签：

相关推荐