his/openhis-server-new/SPRINGBOOT_4_UPGRADE_GUIDE.md

Spring Boot 3.5.14 → 4.0.6 升级操作手册

📅 基于实际编译验证，2026-06-04
⏱️ 预估工时：2-3 天（不含回归测试）

---

一、必须修改的文件清单

Phase 1: POM 版本升级

1.1 父 POM (pom.xml)

<!-- 修改前 -->
<parent>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.14</version>
</parent>

<!-- 修改后 -->
<parent>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.0.6</version>
</parent>

同时需要在 <properties> 中确认：

<!-- Spring Boot 4.0.6 管理的版本 -->
<postgresql.version>42.7.10</postgresql.version>  <!-- 原 42.7.4 -->

1.2 core-framework/pom.xml — Starter 改名

<!-- 修改前 -->
<artifactId>spring-boot-starter-aop</artifactId>

<!-- 修改后 -->
<artifactId>spring-boot-starter-aspectj</artifactId>

原因: SB4 将 spring-boot-starter-aop 重命名为 spring-boot-starter-aspectj

1.3 所有使用 mybatis-plus-spring-boot3-starter 的 POM（7个模块）

保持 mybatis-plus-spring-boot3-starter:3.5.16 不变，但需要添加 spring-boot-jackson2 依赖：

<!-- 在 core-framework/pom.xml 中添加 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-jackson2</artifactId>
</dependency>

---

Phase 2: Java 代码修改

2.1 Jackson 包路径迁移 (1个文件)

文件: core-framework/src/main/java/com/core/framework/config/ApplicationConfig.java

// 修改前
import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;

// 修改后
import org.springframework.boot.jackson2.autoconfigure.Jackson2ObjectMapperBuilderCustomizer;

原因: SB4 将 Jackson 自动配置从 spring-boot-autoconfigure 拆分到独立的 spring-boot-jackson2 模块

2.2 Spring Security 7.0 适配 (可能需要)

检查 SecurityConfig.java 中是否有 Spring Security 7.0 的废弃 API：

• requestMatchers() 可能有新变化
• @EnableMethodSecurity 可能有参数变化

2.3 Tomcat 11 适配 (低风险)

Tomcat 11 基于 Servlet 6.1，与 Jakarta EE 11 对齐。项目已迁移到 jakarta.servlet，理论上兼容。

---

Phase 3: 配置文件变更

3.1 可能的属性重命名

SB4 可能重命名了一些属性。使用 spring-boot-properties-migrator 检测：

<!-- 在 core-framework/pom.xml 中临时添加 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

启动后控制台会输出所有需要迁移的属性。

---

二、已知的 Breaking Changes

2.1 Starter 变化

SB3 Starter	SB4 状态	替代方案
spring-boot-starter-aop	❌ 移除	spring-boot-starter-aspectj
spring-boot-starter-undertow	❌ 移除	spring-boot-starter-tomcat
spring-boot-starter-pulsar-reactive	❌ 移除	无替代

2.2 包路径变化

旧路径	新路径
o.s.b.autoconfigure.jackson.*	o.s.b.jackson2.autoconfigure.*

2.3 Spring Framework 7.0

• 基于 Jakarta EE 11
• 虚拟线程更好的支持
• HTTP 接口增强
• 部分废弃 API 移除

2.4 Spring Security 7.0

• 部分配置方式变化
• OAuth2 相关 API 调整

---

三、第三方依赖兼容性

依赖	当前版本	SB4 兼容性	需要操作
MyBatis Plus	3.5.16 (boot3-starter)	⚠️ 未验证	启动测试，可能需要手动适配
Druid	1.2.28 (boot3-starter)	⚠️ 未验证	启动测试
Flowable	7.1.0	⚠️ 需验证	可能需要升级到 7.2+
Springdoc	2.8.6	✅ 应兼容	验证 OpenAPI 文档
LiteFlow	2.12.4.1	⚠️ 需验证	验证流程引擎
pagehelper	2.1.1	⚠️ 需验证	验证分页功能
fastjson2	2.0.61	⚠️ 注意 Jackson 3 冲突	排除 kotlin-reflect

---

四、推荐执行步骤

Step 1: 创建升级分支

git checkout -b upgrade/springboot-4.0 develop

Step 2: 修改 POM 文件

按 Phase 1 修改所有 POM 文件

Step 3: 修改 Java 代码

按 Phase 2 修改 Java 文件

Step 4: 添加属性迁移器

临时添加 spring-boot-properties-migrator 依赖

Step 5: 编译验证

mvn clean compile -DskipTests

Step 6: 修复编译错误

根据编译错误逐一修复

Step 7: 启动测试

java -jar openhis-application/target/openhis-application.jar --spring.profiles.active=dev --server.port=18082

Step 8: 检查控制台输出

• 查看属性迁移警告
• 检查 Bean 创建错误
• 验证数据库连接
• 验证 Redis 连接

Step 9: 回归测试

• Swagger UI / OpenAPI 文档
• 登录接口
• 核心业务接口
• 前端页面

Step 10: 清理

• 移除 spring-boot-properties-migrator 依赖
• 提交代码

---

五、风险评估

风险项	概率	影响	缓解措施
MyBatis Plus 不兼容	中	高	手动配置 DataSource + SqlSessionFactory
Druid 自动配置失败	中	中	手动配置 DruidDataSource
Flowable 表结构不兼容	低	高	设置 databaseSchemaUpdate=true
Jackson 3 与 fastjson2 冲突	低	中	排除 kotlin-reflect
Spring Security 7.0 配置变化	低	中	参考官方迁移指南

---

六、回退方案

如果升级失败，随时可以回退：

git checkout develop
git branch -D upgrade/springboot-4.0

---

文档生成时间: 2026-06-04 23:15