# 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*