华佗
3578a24254
- 新增 MD/specs/IRON_RULES.md — 执行铁律汇总(v2.0, 8条铁律) - 新增 MD/specs/BACKEND_DEVELOPMENT_STANDARD.md — 后端开发规范 - 新增 MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md — 前端开发规范 - 新增 healthlink-his-ui/AGENTS.md — 前端铁律引用 - 更新 healthlink-his-server/AGENTS.md — 同步规范文档引用 - 修复10个文档缺失的元数据(文档类型标签) - 全部30个文档通过命名规范和元数据检查
193 lines
5.1 KiB
Markdown
193 lines
5.1 KiB
Markdown
# MyBatis Plus 升级方案
|
||
|
||
> **文档类型**: 升级记录
|
||
> **适用范围**: MyBatis-Plus组件
|
||
> **版本**: v1.0
|
||
|
||
> **编制日期**: 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
|
||
<!-- 在 healthlink-his-server/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 覆盖（关键！）
|
||
|
||
在 `healthlink-his-server/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 healthlink-his-server
|
||
mvn clean compile -DskipTests
|
||
```
|
||
|
||
### Step 4: 功能验证清单
|
||
|
||
| 验证项 | 测试方法 | 通过标准 |
|
||
|---|---|---|
|
||
| 登录 | 输入账号密码 | 登录成功 |
|
||
| 分页查询 | 访问列表页 | 分页正常 |
|
||
| 新增 | 提交表单 | 数据写入 |
|
||
| 编辑 | 修改并保存 | 数据更新 |
|
||
| 删除 | 删除记录 | 软删除成功 |
|
||
| 批量操作 | 批量新增/删除 | 全部成功 |
|
||
| 多租户 | 切换租户 | 数据隔离正确 |
|
||
| 乐观锁 | 并发更新 | 冲突检测正确 |
|
||
| 导出 | Excel 导出 | 文件正常 |
|
||
|
||
### Step 5: 提交代码
|
||
|
||
```bash
|
||
git add healthlink-his-server/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 分钟
|
||
|