his/docs/MYBATIS_PLUS_UPGRADE_PLAN.md

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 中显式锁定关键依赖版本

<!-- 在 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

<!-- 在 <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: 修改版本号

<!-- 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> 中添加：

<!-- 覆盖 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: 编译验证

cd openhis-server-new
mvn clean compile -DskipTests

Step 4: 功能验证清单

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

Step 5: 提交代码

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

---

四、回滚方案

如果升级后出现问题：

# 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 分钟