# MyBatis Plus 升级方案

> **编制日期**: 2026-06-04
> **当前版本**: 3.5.5
> **目标版本**: 3.5.16 (最新稳定版, 2026-01-11)
> **Spring Boot**: 2.5.15（保持不变，不升级）

---

## 一、兼容性分析

### 关键发现

| 项目 | 3.5.5 | 3.5.16 | 结论 |
|---|---|---|---|
| `mybatis-spring` | 2.1.2 | 2.1.2 | ✅ 一致 |
| `spring-boot-dependencies` BOM | 2.7.15 | 2.7.18 | ⚠️ BOM 导入，需处理 |
| `mybatis-plus-boot-starter` | 存在 | 存在 | ✅ 兼容 Spring Boot 2.x |
| `mybatis-plus-spring-boot3-starter` | 存在 | 存在 | 我们不用 |

### BOM 冲突处理

MyBatis Plus 3.5.16 的 `mybatis-plus-boot-starter` 在 `dependencyManagement` 中导入了 `spring-boot-dependencies:2.7.18` BOM。这**可能覆盖**我们项目中由 `spring-boot-starter-parent:2.5.15` 管理的依赖版本。

**解决方案：在父 pom.xml 中显式锁定关键依赖版本**

```xml
<!-- 在 openhis-server-new/pom.xml 的 <properties> 中添加 -->
<!-- 锁定 Spring Boot 管理的核心依赖版本，防止被 BOM 覆盖 -->
<spring-boot.version>2.5.15</spring-boot.version>
<spring-boot-dependencies.version>2.5.15</spring-boot-dependencies.version>
```

**更安全的方案：在父 pom.xml 中覆盖 BOM**

```xml
<!-- 在 <dependencyManagement> 中添加，优先级高于 BOM 导入 -->
<dependencyManagement>
    <dependencies>
        <!-- 覆盖 Spring Boot BOM，锁定 2.5.15 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>${spring-boot.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

---

## 二、升级收益

### 🔴 重要 Bug 修复

| Bug | 影响 |
|---|---|
| 多租户查询问题 | ⭐⭐⭐ 我们用了多租户插件 |
| 租户插件 exists 语句失效 | ⭐⭐⭐ exists 子查询场景 |
| 逻辑删除 + 乐观锁冲突 | ⭐⭐⭐ 我们同时用了这两个特性 |
| 批量操作异步异常 | ⭐⭐ 批量导入场景 |
| Db count 返回 null 空指针 | ⭐⭐ 统计查询 |
| 动态 SQL 注释导致合并错误 | ⭐⭐ 复杂 SQL |

### 🟢 新增能力

| 功能 | 说明 |
|---|---|
| `LambdaUpdateWrapper.setIncrBy/setDecrBy` | 字段自增自减 |
| `BaseMapper` 批量操作 + `InsertOrUpdate` | 批量导入增强 |
| `UpdateWrapper.checkSqlInjection` | SQL 注入防护 |
| `deleteByIds` 空集合处理 | 防空指针 |
| `DynamicTableNameJsqlParserInnerInterceptor` | 动态表处理 |
| `OrderItem.withExpression` | 表达式排序 |

### 📦 自动获得的依赖升级

| 组件 | 旧版本 | 新版本 |
|---|---|---|
| MyBatis | 3.5.13 | 3.5.19 |
| JSqlParser | 4.6 | 5.2 |
| jackson | 2.16 | 2.20.1 |
| PostgreSQL | 42.2.27 | 42.7.8 |

---

## 三、升级步骤

### Step 1: 修改版本号

```xml
<!-- pom.xml -->
<mybatis-plus.version>3.5.5</mybatis-plus.version>
<!-- 改为 -->
<mybatis-plus.version>3.5.16</mybatis-plus.version>
```

### Step 2: 添加 BOM 覆盖（关键！）

在 `openhis-server-new/pom.xml` 的 `<dependencyManagement>` 中添加：

```xml
<!-- 覆盖 MyBatis Plus 导入的 Spring Boot BOM，保持 2.5.15 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-dependencies</artifactId>
    <version>2.5.15</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>
```

### Step 3: 编译验证

```bash
cd openhis-server-new
mvn clean compile -DskipTests
```

### Step 4: 功能验证清单

| 验证项 | 测试方法 | 通过标准 |
|---|---|---|
| 登录 | 输入账号密码 | 登录成功 |
| 分页查询 | 访问列表页 | 分页正常 |
| 新增 | 提交表单 | 数据写入 |
| 编辑 | 修改并保存 | 数据更新 |
| 删除 | 删除记录 | 软删除成功 |
| 批量操作 | 批量新增/删除 | 全部成功 |
| 多租户 | 切换租户 | 数据隔离正确 |
| 乐观锁 | 并发更新 | 冲突检测正确 |
| 导出 | Excel 导出 | 文件正常 |

### Step 5: 提交代码

```bash
git add openhis-server-new/pom.xml
git commit -m "chore(deps): MyBatis Plus 3.5.5 → 3.5.16"
git push origin develop
```

---

## 四、回滚方案

如果升级后出现问题：

```bash
# 1. 改回旧版本
<mybatis-plus.version>3.5.5</mybatis-plus.version>

# 2. 删除 BOM 覆盖（如果添加了）

# 3. 重新编译
mvn clean package -DskipTests

# 4. 重启服务
```

---

## 五、风险评估

| 风险 | 概率 | 影响 | 缓解措施 |
|---|---|---|---|
| BOM 版本覆盖 | 中 | 高 | 显式锁定 Spring Boot 版本 |
| 依赖冲突 | 低 | 中 | `mvn dependency:tree` 检查 |
| API 变化 | 低 | 低 | 3.5.x 无 Breaking Changes |
| 分页插件变化 | 低 | 中 | 测试分页查询 |

---

## 六、执行计划

```
Step 1: 修改版本号 (2 分钟)
Step 2: 添加 BOM 覆盖 (2 分钟)
Step 3: mvn clean compile (2 分钟)
Step 4: mvn clean package -DskipTests (2 分钟)
Step 5: 重启后端 (1 分钟)
Step 6: 功能验证 (30 分钟)
Step 7: 提交代码 (1 分钟)
```

**总工时**: 约 40 分钟