增量迁移指南
老 MyBatis-Plus 项目一步步引入 MyBatisGX,不打断现有功能。
迁移思路
共存的目的是"老代码零改动,新代码用 MyBatisGX"。推荐的迁移路径是自底向上:
第 1 步:引入共存 starter,项目跑通
第 2 步:迁移配置前缀(mybatis-plus.* → mybatisgx.*)
第 3 步:新建 MyBatisGX DAO,新功能用它开发
第 4 步:按模块逐步把查询迁到 MyBatisGX
第 5 步(可选):完全迁移后移除 MP 依赖
第 1 步:引入共存 starter
<!-- Spring Boot 3 -->
<dependency>
<groupId>com.mybatisgx</groupId>
<artifactId>mybatisgx-spring-boot3-mp-compat-starter</artifactId>
<version>0.4.0</version>
</dependency>
sb2 用 mybatisgx-spring-boot2-mp-compat-starter。引入后先启动一次,确认:
- 只创建一个
SqlSessionFactory(由 MP 创建) - 老
BaseMapper接口照常工作
第 2 步:迁移配置前缀
共存 starter 的 MybatisgxAutoConfiguration 继承 MP 自动配置,mybatis-plus.* 前缀不再生效。
将原有 MP 配置迁移到 mybatisgx.* 下:
# 迁移前(MP 前缀)
# mybatis-plus:
# configuration:
# map-underscore-to-camel-case: true
# global-config:
# banner: false
# 迁移后(MyBatisGX 前缀)
mybatisgx:
configuration:
databaseId: MySQL
map-underscore-to-camel-case: true
cache-enabled: false
global-config:
banner: false
databaseId 尤其重要——MyBatisGX 的多数据库方言适配依赖它,共存时拿不到会导致
SQL 方言判断错误。测试环境用 H2(MODE=MySQL)时显式设置 databaseId: MySQL 即可。
第 3 步:新建 MyBatisGX DAO
新增 dao 包(或沿用现有包),定义继承 SimpleDao / CurdDao / SelectDao 的接口。
实体同时标注两套注解(见 快速开始 的实体示例):
@Mapper
public interface UserDao extends SimpleDao<User, UserQuery, Long> {
// 方法名派生 SQL:findByNameLike → WHERE name LIKE ...
List<User> findByNameLike(@Param("name") String name);
// 查询实体:直接使用 SelectDao 内置的 findList(UserQuery)
}
将新 dao 包加入启动类的 @MybatisgxScan.daoBasePackages,与 mapper 包一起扫描。
第 4 步:按模块迁移查询
对每个模块,把"查询逻辑"从 Service 里的 Wrapper 迁移到 DAO 方法:
// 迁移前(MP Wrapper)
List<User> list = userMapper.selectList(
new LambdaQueryWrapper<User>()
.like(User::getName, "张")
.gt(User::getAge, 25));
// 迁移后(MyBatisGX 方法名派生)
List<User> list = userDao.findByNameLikeAndAgeGt("张", 25);
迁移节奏由你掌控:复杂查询可以先保留 Wrapper,简单的先迁。
第 5 步(可选):完全迁移后移除 MP
当所有查询都迁移到 MyBatisGX 后:
- 删除
mybatisgx-spring-boot3-mp-compat-starter依赖 - 恢复使用
mybatisgx-spring-boot3-starter(标准 starter) - MyBatisGX DAO 接口迁移回标准 starter 的扫描方式(标准
@MybatisgxScan) - 删除 MP 的
BaseMapper接口与@TableName注解
core 中新增的 MybatisgxConfigurationAware 接口在无 MP 场景下不影响任何行为,可放心回退。
迁移注意事项
- 不要同时引入标准 starter 与 mp-compat-starter(互斥)
- 不要让一个接口同时继承
BaseMapper与 MyBatisGX DAO 基类 - 逻辑删除、分页等能力两套框架独立工作,迁移时留意行为差异(见 故障排查)