Skip to content

feat: Spring Boot 2 → 3 升级 #2

Open
Open
feat: Spring Boot 2 → 3 升级#2
Labels
featureNew featureready-for-agentReady for agent implementation

Description

@WhyWhatHow
WhyWhatHow
opened on Jul 18, 2026

Spring Boot 2 → 4 升级计划

状态：Draft
创建时间：2025-07-18
Issue Type: feature

Problem Statement

Fun-Project 当前使用 Spring Boot 2.6.3（已于 2022 年停止维护），存在以下问题：

  1. 安全风险：Spring Boot 2.x 已停止安全更新，存在已知漏洞
  2. 依赖过旧：Spring Cloud 2021.0.1、Spring Cloud Alibaba 2021.1 等依赖版本过旧
  3. JDK 限制：当前使用 JDK 1.8，无法使用现代 Java 特性（Records、Pattern Matching、Virtual Threads 等）
  4. Spring Security OAuth2 过时：使用已废弃的 spring-security-oauth2 库，需要迁移到 Spring Authorization Server
  5. 技术债务：大量 javax.* 引用需要迁移到 jakarta.*

升级到 Spring Boot 3.2.x（或 4.x 稳定版）是所有后续功能开发的前置条件。

Solution

将项目从 Spring Boot 2.6.3 升级到 Spring Boot 3.2.x，同步升级所有配套依赖，确保现有功能正常运行。

版本映射

组件 当前版本 目标版本
JDK 1.8 17
Spring Boot 2.6.3 3.2.x
Spring Cloud 2021.0.1 2023.0.x
Spring Cloud Alibaba 2021.1 2023.0.x
MyBatis-Plus 3.5.1 3.5.5+
SpringDoc 1.6.6 2.3.0+
Druid 1.2.8 1.2.20+
Spring Security OAuth2 旧版 移除，使用 Spring Authorization Server
Spring Boot Admin 2.6.7 3.2.x

User Stories

Phase 1: JDK 升级

  1. 作为开发者，我希望将 JDK 从 1.8 升级到 17，以便使用现代 Java 特性
  2. 作为开发者，我希望修改 pom.xml 中的 maven.compiler.source/target 为 17，以便项目使用 JDK 17 编译
  3. 作为开发者，我希望修复 JDK 17 不兼容的代码，以便项目能在 JDK 17 上正常运行

Phase 2: javax → jakarta 迁移

  1. 作为开发者，我希望将所有 javax.servlet 替换为 jakarta.servlet，以便兼容 Jakarta EE 9+
  2. 作为开发者，我希望将所有 javax.validation 替换为 jakarta.validation，以便兼容 Bean Validation 3.0
  3. 作为开发者，我希望将所有 javax.annotation 替换为 jakarta.annotation，以便兼容 Jakarta Annotations 2.0
  4. 作为开发者，我希望将所有 javax.persistence 替换为 jakarta.persistence，以便兼容 JPA 3.0
  5. 作为开发者，我希望将所有 javax.sql 保留不变，因为 javax.sql.DataSource 未迁移

Phase 3: Spring Boot 升级

  1. 作为开发者，我希望将 spring-boot.version 从 2.6.3 升级到 3.2.x，以便使用最新特性
  2. 作为开发者，我希望将 spring-cloud.version 从 2021.0.1 升级到 2023.0.x，以便与 Boot 3 兼容
  3. 作为开发者，我希望将 spring-cloud-alibaba.version 从 2021.1 升级到 2023.0.x，以便与 Boot 3 兼容
  4. 作为开发者，我希望移除 spring-boot-starter-redis 依赖，因为 Boot 3 中已移除该 starter
  5. 作为开发者，我希望使用 spring-boot-starter-data-redis 替代，以便正确集成 Redis

Phase 4: Spring Security 迁移

  1. 作为开发者，我希望移除 spring-security-oauth2 依赖，因为该库已废弃
  2. 作为开发者，我希望引入 spring-boot-starter-oauth2-authorization-server，以便使用 Spring Authorization Server
  3. 作为开发者，我希望将 AuthorizationServerConfigurerAdapter 迁移到新版配置，以便兼容 Spring Security 6.x
  4. 作为开发者，我希望将 ResourceServerConfigurerAdapter 迁移到 SecurityFilterChain，以便兼容 Spring Security 6.x
  5. 作为开发者，我希望将 WebSecurityConfigurerAdapter 迁移到 SecurityFilterChain，以便兼容 Spring Security 6.x
  6. 作为开发者，我希望将 RedisTokenStore 迁移到新版实现，以便兼容 Spring Authorization Server
  7. 作为开发者，我希望将 RemoteTokenServices 迁移到新版实现，以便兼容 Spring Authorization Server
  8. 作为开发者，我希望保留现有的 OAuth2 客户端配置（sys_oauth_client_details 表），以便平滑迁移
  9. 作为开发者，我希望保留现有的 Token 增强逻辑（TokenEnhancer），以便平滑迁移

Phase 5: MyBatis-Plus 升级

  1. 作为开发者，我希望将 MyBatis-Plus 从 3.5.1 升级到 3.5.5+，以便与 Boot 3 兼容
  2. 作为开发者，我希望验证所有 MyBatis-Plus 注解（@TableName、@TableId 等）正常工作
  3. 作为开发者，我希望验证所有 MyBatis-Plus 代码生成器正常工作

Phase 6: SpringDoc 升级

  1. 作为开发者，我希望将 SpringDoc 从 1.6.6 升级到 2.3.0+，以便与 Boot 3 兼容
  2. 作为开发者，我希望将 springdoc-openapi-webflux-ui 替换为 springdoc-openapi-starter-webflux-ui，以便使用新版 API
  3. 作为开发者，我希望验证 Swagger UI 正常访问
  4. 作为开发者，我希望验证动态 API 分组功能正常工作

Phase 7: 其他依赖升级

  1. 作为开发者，我希望将 Druid 从 1.2.8 升级到 1.2.20+，以便与 Boot 3 兼容
  2. 作为开发者，我希望将 Spring Boot Admin 从 2.6.7 升级到 3.2.x，以便与 Boot 3 兼容
  3. 作为开发者，我希望将 Hutool 从 5.4.1 升级到 5.8.x，以便使用最新特性
  4. 作为开发者，我希望将 Fastjson 从 1.2.78 升级到 Fastjson2 2.0.x，以便修复安全漏洞
  5. 作为开发者，我希望验证 multilevel-cache-spring-boot-starter 与 Boot 3 兼容
  6. 作为开发者，我希望验证 oss-spring-boot-starter 与 Boot 3 兼容

Phase 8: 配置文件迁移

  1. 作为开发者，我希望更新 application.yml 配置文件，以便兼容 Boot 3 配置格式
  2. 作为开发者，我希望更新 bootstrap.yml 配置文件，以便兼容 Boot 3 配置格式
  3. 作为开发者，我希望验证 Nacos 配置中心正常工作
  4. 作为开发者，我希望验证多环境配置（dev/test/prod）正常切换

Phase 9: 测试验证

  1. 作为开发者，我希望所有模块编译通过，以便确认依赖升级成功
  2. 作为开发者，我希望所有单元测试通过，以便确认代码迁移正确
  3. 作为开发者，我希望集成测试：登录流程正常工作
  4. 作为开发者，我希望集成测试：OAuth2 授权流程正常工作
  5. 作为开发者，我希望集成测试：网关路由正常工作
  6. 作为开发者，我希望集成测试：微服务间调用正常工作
  7. 作为开发者，我希望 Docker 镜像正常构建和运行

Phase 10: 文档更新

  1. 作为开发者，我希望更新 README.md，记录新的版本要求
  2. 作为开发者，我希望更新部署文档，记录 JDK 17 要求
  3. 作为开发者，我希望更新 docker-compose.yml，使用 JDK 17 基础镜像

Implementation Decisions

1. 升级策略：渐进式升级

决策：采用渐进式升级策略，分阶段完成，每阶段可独立验证。

理由：

  • 一次性升级风险过高，问题难以定位
  • 渐进式升级可以逐步验证每个模块
  • 可以在升级过程中保持部分功能可用

2. JDK 版本选择：JDK 17

决策：选择 JDK 17 作为目标版本，而非 JDK 21。

理由：

  • JDK 17 是 LTS 版本，长期支持
  • Spring Boot 3.x 最低要求 JDK 17
  • JDK 21 的 Virtual Threads 等特性可以后续再启用
  • 降低升级风险

3. Spring Security OAuth2 迁移策略

决策：保留现有 OAuth2 业务逻辑，仅迁移配置类。

理由：

  • 现有的 FunClientDetailsService、TokenEnhancer 等业务逻辑可以复用
  • 只需迁移配置类（AuthorizationServerConfigurerAdapter → 新版配置）
  • 保留 sys_oauth_client_details 表结构
  • 保留 Redis Token Store 方案

迁移映射：

  • AuthorizationServerConfigurerAdapter → @Bean RegisteredClientRepository + @Bean AuthorizationService
  • ResourceServerConfigurerAdapter → SecurityFilterChain
  • WebSecurityConfigurerAdapter → SecurityFilterChain
  • RedisTokenStore → RedisOAuth2AuthorizationService
  • RemoteTokenServices → OAuth2TokenIntrospectionClient

4. javax → jakarta 迁移方式

决策：使用 IDE 批量替换 + 手动验证。

理由：

  • 项目中有 101 处 javax.* 引用
  • 大部分是 javax.servlet、javax.validation、javax.annotation
  • javax.sql.DataSource 不需要迁移（属于 Java SE）
  • 批量替换后需要逐模块验证

5. MyBatis-Plus 升级策略

决策：直接升级到 3.5.5+，无需修改业务代码。

理由：

  • MyBatis-Plus 3.5.x 系列向后兼容
  • 3.5.5+ 已支持 Boot 3
  • 现有的 @TableName、@TableId 等注解无需修改

6. SpringDoc 升级策略

决策：从 SpringDoc 1.x 升级到 2.x，修改依赖和少量配置。

理由：

  • SpringDoc 2.x 是 Boot 3 的官方支持版本
  • API 注解（@Operation、@Schema 等）无需修改
  • 需要修改依赖名称：springdoc-openapi-webflux-ui → springdoc-openapi-starter-webflux-ui

7. 模块升级顺序

决策：按依赖关系从底层到上层升级。

顺序：

  1. fun-common-core（无外部依赖）
  2. fun-common-validation（依赖 fun-common-core）
  3. fun-common-web（依赖 fun-common-core）
  4. fun-common-log（依赖 fun-common-core）
  5. fun-common-security（依赖 fun-common-web）
  6. fun-common-captcha（依赖 fun-common-web）
  7. fun-common-cache（依赖 fun-common-core）
  8. fun-api/fun-system-api（依赖 fun-common-core）
  9. fun-config（配置模块）
  10. fun-auth（依赖 fun-common-security）
  11. fun-gateway（依赖 fun-common-core）
  12. fun-service/fun-service-system（依赖 fun-api）

8. 向后兼容性

决策：不保留向后兼容性，直接升级到新版本。

理由：

  • 项目已停止维护 2 年，无需考虑旧版本兼容
  • 一次性升级到最新版本，避免技术债务累积
  • 简化升级过程

Testing Decisions

测试策略

  1. 单元测试：验证每个模块的独立功能
  2. 集成测试：验证模块间交互
  3. 端到端测试：验证完整业务流程

测试优先级

优先级 测试内容 说明
P0 编译测试 所有模块编译通过
P0 启动测试 所有服务正常启动
P1 登录测试 用户名密码登录正常
P1 OAuth2 测试 Token 签发、验证正常
P1 网关测试 路由转发正常
P2 权限测试 RBAC 权限校验正常
P2 缓存测试 多级缓存正常工作
P3 Swagger 测试 API 文档正常访问

测试用例

编译测试

mvn clean compile -DskipTests

启动测试

# 启动 Nacos
docker-compose up -d fun-nacos fun-redis

# 启动各服务
mvn spring-boot:run -pl fun-auth
mvn spring-boot:run -pl fun-gateway
mvn spring-boot:run -pl fun-service/fun-service-system

登录测试

# 获取 Token
curl -X POST http://localhost:10000/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=admin&password=admin&client_id=fun&client_secret=fun"

# 验证 Token
curl http://localhost:10000/oauth/check_token?token=<token>

网关测试

# 通过网关访问服务
curl http://localhost:9000/fun-service-system/user/details/1 \
  -H "Authorization: Bearer <token>"

Out of Scope

  1. Spring Boot 4.x：当前 Boot 4 尚未发布稳定版，先升级到 3.2.x
  2. JDK 21：Virtual Threads 等特性可以后续再启用
  3. 新功能开发：本次升级仅涉及版本迁移，不包含新功能
  4. 数据库 schema 变更：保留现有的表结构
  5. 前端变更：本次升级不影响前端

Further Notes

风险点

  1. Spring Security OAuth2 变更较大

    • 风险：配置类需要重写
    • 缓解：保留业务逻辑，仅迁移配置类

  2. 第三方库兼容性

    • 风险：部分库可能不兼容 Boot 3
    • 缓解：提前验证兼容性，必要时寻找替代方案

  3. Nacos 配置方式变化

    • 风险：Boot 3 的配置加载方式有变化
    • 缓解：参考 Spring Cloud Alibaba 官方文档

  4. Spring Gateway 配置变化

    • 风险：Gateway 的部分配置可能需要调整
    • 缓解：参考 Spring Cloud Gateway 官方文档

参考文档

预估工时

阶段 工时 说明
Phase 1: JDK 升级 0.5天 修改配置
Phase 2: javax → jakarta 1天 批量替换 + 验证
Phase 3: Spring Boot 升级 1天 依赖升级
Phase 4: Spring Security 迁移 2天 最复杂部分
Phase 5: MyBatis-Plus 升级 0.5天 简单升级
Phase 6: SpringDoc 升级 0.5天 简单升级
Phase 7: 其他依赖升级 0.5天 简单升级
Phase 8: 配置文件迁移 0.5天 配置调整
Phase 9: 测试验证 1天 全面测试
Phase 10: 文档更新 0.5天 更新文档
总计 8天 包含问题修复

Checklist

  • 创建升级分支 feature/springboot3-upgrade
  • 安装 JDK 17
  • 修改 pom.xml 版本号
  • 完成 javax → jakarta 迁移
  • 完成 Spring Security OAuth2 迁移
  • 所有模块编译通过
  • 所有服务正常启动
  • 登录流程正常
  • OAuth2 流程正常
  • 网关路由正常
  • Docker 镜像正常构建
  • 更新文档

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureNew featureready-for-agentReady for agent implementation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions