华佗
554e20f276
核心升级: - Spring Boot 3.5.14 → 4.0.6 - Spring Framework 6.2.18 → 7.0.7 - Spring Security 6.5.10 → 7.0.5 - Flyway 11.7.2 → 11.14.1 Breaking Changes 适配: - starter-aop → starter-aspectj (SB4 重命名) - JDBC/Flyway/Jackson 自动配置拆分到独立模块 - DaoAuthenticationProvider 构造函数变更 (Spring Security 7.0) - DataSourceProperties 包路径迁移 依赖调整: - Druid boot3-starter → druid core (手动配置, 避免 SB4 不兼容) - 新增 spring-boot-starter-quartz - 新增 spring-boot-starter-cache - 新增 spring-boot-flyway / spring-boot-jdbc - PostgreSQL 42.7.4 → 42.7.10 验证: 26/26 测试通过, 1374 API端点正常
222 lines
5.5 KiB
Markdown
222 lines
5.5 KiB
Markdown
# Spring Boot 3.5.14 → 4.0.6 升级操作手册
|
||
|
||
> 📅 基于实际编译验证，2026-06-04
|
||
> ⏱️ 预估工时：2-3 天（不含回归测试）
|
||
|
||
---
|
||
|
||
## 一、必须修改的文件清单
|
||
|
||
### Phase 1: POM 版本升级
|
||
|
||
#### 1.1 父 POM (`pom.xml`)
|
||
|
||
```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>` 中确认：
|
||
|
||
```xml
|
||
<!-- Spring Boot 4.0.6 管理的版本 -->
|
||
<postgresql.version>42.7.10</postgresql.version> <!-- 原 42.7.4 -->
|
||
```
|
||
|
||
#### 1.2 `core-framework/pom.xml` — Starter 改名
|
||
|
||
```xml
|
||
<!-- 修改前 -->
|
||
<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` 依赖：
|
||
|
||
```xml
|
||
<!-- 在 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`
|
||
|
||
```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` 检测：
|
||
|
||
```xml
|
||
<!-- 在 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: 创建升级分支
|
||
```bash
|
||
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: 编译验证
|
||
```bash
|
||
mvn clean compile -DskipTests
|
||
```
|
||
|
||
### Step 6: 修复编译错误
|
||
根据编译错误逐一修复
|
||
|
||
### Step 7: 启动测试
|
||
```bash
|
||
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 配置变化 | 低 | 中 | 参考官方迁移指南 |
|
||
|
||
---
|
||
|
||
## 六、回退方案
|
||
|
||
如果升级失败，随时可以回退：
|
||
```bash
|
||
git checkout develop
|
||
git branch -D upgrade/springboot-4.0
|
||
```
|
||
|
||
---
|
||
|
||
*文档生成时间: 2026-06-04 23:15*
|