若依框架从 Spring Boot 2 升级到 Spring Boot 3 实战

若依框架从 Spring Boot 2 升级到 Spring Boot 3

一、升级前准备

确认若依版本：优先选择若依官方已适配 Spring Boot 3 的版本（如 RuoYi v4.7.0+ 有适配分支），若使用自定义改造版本，需逐一处理兼容性问题。
环境要求：Spring Boot 3 要求 JDK 17+（放弃 JDK 8/11 支持），需先升级本地 / 服务器 JDK 到 17 及以上。
备份代码：升级前完整备份项目代码，避免升级过程中代码丢失。

二、核心升级步骤

1. 升级 Maven/Gradle 依赖

核心是修改 pom.xml（Maven）或 build.gradle（Gradle）中的依赖版本，以下以 Maven 为例：

（1）修改父依赖为 Spring Boot 3

<!-- 原 Spring Boot 2 依赖 -->
<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>2.7.12</version>
  <relativePath/>
</parent>
<!-- 升级为 Spring Boot 3.x（推荐 3.2.x 稳定版） -->
<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.2.3</version>
  <relativePath/>
</parent>

（2）升级 Spring Cloud 依赖（若使用微服务版本）

Spring Boot 3 对应 Spring Cloud 2022.x 及以上版本（不再使用 Finchley/Greenwich 等版本号，改为年份命名）：

<!-- Spring Cloud 版本管理 -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-dependencies</artifactId>
      <version>2022.0.4</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

（3）升级若依核心依赖

若依核心依赖需适配 Spring Boot 3，建议使用官方适配版本：

<!-- 若依核心依赖（以单体版为例） -->
<dependency>
  <groupId>com.ruoyi</groupId>
  <artifactId>ruoyi-common</artifactId>
  <version>4.8.0</version> <!-- 4.8.0+ 适配 Spring Boot 3 -->
</dependency>

（4）替换不兼容依赖

Spring Boot 3 移除了 javax.* 包，替换为 jakarta.*（核心变更）：

<!-- 原 JAXB 依赖（javax） -->
<dependency>
  <groupId>javax.xml.bind</groupId>
  <artifactId>jaxb-api</artifactId>
</dependency>
<!-- 替换为 jakarta 版本 -->
<dependency>
  <groupId>jakarta.xml.bind</groupId>
  <artifactId>jakarta.xml.bind-api</artifactId>
  <version>4.0.1</version>
</dependency>
<dependency>
  <groupId>com.sun.xml.bind</groupId>
  <artifactId>jaxb-impl</artifactId>
  <version>4.0.2</version>
  <scope>runtime</scope>
</dependency>

校验相关依赖（如 Hibernate Validator）：

<!-- Spring Boot 3 中 validator 已适配 jakarta -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

2. 修改配置文件

（1）移除 / 替换过时配置

Spring Boot 3 废弃了部分配置项，需调整 application.yml/application.properties：

原 server.servlet.context-path 改为 server.servlet.context-path（无变化，但需检查其他配置）；
数据源配置无核心变化，但需确保数据库驱动适配 JDK 17（如 MySQL 驱动升级到 8.0.30+）：

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/ruoyi?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
    username: root
    password: root

（2）调整日志配置（可选）

Spring Boot 3 对日志框架的适配无大变化，但需确保 logback.xml 中无 javax.* 相关引用。

3. 代码层面兼容修改

（1）替换 `javax` 为 `jakarta` 导入

项目中所有 import javax.xxx 需替换为 import jakarta.xxx，核心场景：

// 原导入
import javax.validation.Valid;
import javax.validation.constraints.NotNull;
import javax.annotation.PostConstruct;

// 替换为
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotNull;
import jakarta.annotation.PostConstruct;

Servlet 相关：HttpServletRequest、HttpServletResponse 等（若直接导入）：

// 原导入
import javax.servlet.http.HttpServletRequest;

// 替换为
import jakarta.servlet.http.HttpServletRequest;

（2）调整 Spring Security 配置（关键）

Spring Boot 3 对应 Spring Security 6.x，若依的权限模块需适配：

// 原配置方式（Spring Boot 2）
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        // 权限配置
    }
}

// 升级后（Spring Boot 3/Security 6）
@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/login", "/captcha").permitAll()
                .anyRequest().authenticated()
            )
            .formLogin(form -> form
                .loginProcessingUrl("/login")
                .successHandler(authenticationSuccessHandler)
                .failureHandler(authenticationFailureHandler)
            )
            .logout(logout -> logout
                .logoutUrl("/logout")
                .logoutSuccessHandler(logoutSuccessHandler)
            )
            .csrf(csrf -> csrf.disable()); // 若依默认关闭 CSRF，需适配新写法
        return http.build();
    }
}

（3）其他兼容调整

若使用 Redis，Spring Data Redis 3.x 无核心 API 变化，但需确保序列化方式兼容；
若依的定时任务、代码生成器等模块，需检查是否有 javax 相关引用，逐一替换。

三、测试验证

编译项目：执行 mvn clean compile，修复所有编译错误（主要是依赖缺失、导入错误）；
启动项目：检查启动日志，修复 Bean 初始化失败、配置加载异常等问题；
功能测试：验证登录、菜单、权限、数据 CRUD 等核心功能是否正常；
兼容性测试：验证第三方集成（如 OSS、短信、支付）是否适配 JDK 17 + Spring Boot 3。

四、总结

核心前提：升级 JDK 到 17+，替换所有 javax.* 依赖为 jakarta.*；
关键步骤：升级 Spring Boot 3 父依赖、适配 Spring Security 6 配置、替换代码中 javax 导入；
验证重点：编译无错误、启动无异常、核心功能正常，是升级成功的核心标准。

若依框架从 Spring Boot 2 升级到 Spring Boot 3 实战