跳到主要内容

故障排查

共存模式下常见陷阱与解决方案。

1. 逻辑删除语义不一致​

MyBatisGX 与 MP 的逻辑删除是两套独立机制,实现位置完全不同:

框架机制读取的注解
MyBatisGXSQL 生成期硬编码(where 自动追加条件、delete 改写为 UPDATE)@LogicDelete
MyBatis-Plus拦截器期动态拼装@TableLogic

同一实体若只在一边标注,另一边不会遵循:

// 实体只标了 MyBatisGX 的 @LogicDelete,没标 MP 的 @TableLogic
@TableName("t_user")
public class User {
@LogicDelete(show = "0", hide = "1") // MyBatisGX 逻辑删除
private Integer deleted;
// 未标 @TableLogic → MP 侧走真删
}

userDao.deleteById(1L); // → UPDATE t_user SET deleted='0' WHERE id=1 ✅ 软删
userMapper.deleteById(1L); // → DELETE FROM t_user WHERE id=1 ❌ 物理删除

建议:同一实体要么两套注解都标注(语义一致),要么只在其中一边操作该实体。 混用场景需自行保证数据一致性。

2. mybatis-plus.* 配置不再生效​

共存 starter 用 MybatisgxAutoConfiguration(继承 MP 自动配置)替换了 MP 的原自动配置, mybatis-plus.* 前缀下的配置(含 global-config、db-config)不再生效。

# 不生效
# mybatis-plus:
# configuration:
# map-underscore-to-camel-case: true

# 生效
mybatisgx:
configuration:
map-underscore-to-camel-case: true

databaseId 尤其要命——MyBatisGX 的方言适配依赖它,配置缺失会导致方言判断错误。 用 H2(MODE=MySQL)测试时显式设置 databaseId: MySQL。

3. 标准 starter 与 compat starter 互斥​

com.mybatisgx.boot.MybatisgxScan 同时存在于标准 starter 与 mp-compat-starter 两个 jar (全限定名相同、行为不同)。同时引入两个 starter 时类加载顺序决定行为,不可预测且无报错。

<!-- 错误:同时引入 -->
<dependency>
<artifactId>mybatisgx-spring-boot3-starter</artifactId>
</dependency>
<dependency>
<artifactId>mybatisgx-spring-boot3-mp-compat-starter</artifactId>
</dependency>

解决:只保留 compat starter(共存场景)或只保留标准 starter(纯 MyBatisGX 场景)。

4. 误引入 mybatis-spring-boot-starter 导致冲突​

共存模式下 SqlSessionFactory 由 MP 创建。若间接依赖带入了 mybatis-spring-boot-starter, 其 MybatisAutoConfiguration 会与 MP 的 MybatisPlusAutoConfiguration 同时注册 sqlSessionFactory bean,导致 BeanDefinitionOverrideException 或 bean 名冲突。

解决:排查依赖树(mvn dependency:tree),排除 mybatis-spring-boot-starter; 共存 starter 已内置 MybatisgxExcludeAutoConfigFilter 排除原生 MybatisAutoConfiguration。

5. 双继承检测​

一个接口同时继承 BaseMapper 与 MyBatisGX DAO 基类:

  • 编译期:BaseMapper 与 CurdDao 的 deleteById 等方法参数签名冲突,Java 直接报 name clash,无法编译
  • 运行期:MybatisgxDoubleInheritanceChecker 作为二次防线,启动时遍历 mapper 接口, 发现双继承直接报错

正常接口不会被误报(仅继承 BaseMapper 或仅继承 Dao 均通过,集成测试已覆盖)。

6. 升级 MP / mybatis 版本后的二进制问题​

MybatisgxPlusConfiguration 通过 copyNonFinalFields 反射拷贝 MP 的 MybatisConfiguration 字段(sb3 线)。若未来 MP 新增 final 字段,新 Configuration 里该字段为默认值,可能运行期 NPE。

建议:升级 MP 大版本时回归验证共存场景;不要手动把 mybatis 拉到低于 core-patch 编译基线(3.5.19)的版本,否则可能触发 NoSuchMethodError。

7. 接口扫描注解需全工程统一(@Mapper vs @Repository 二选一)​

共存模式只用 @MybatisgxScan 承载的 @MapperScan 注册 mapper bean(@MapperScan 注解无需单独声明),其 annotationClass 是单一过滤条件——工程内所有 DAO / mapper 接口必须统一使用同一种注解,并让 annotationClass 与之一致:

  • 老工程用 @Mapper → 新模块也用 @Mapper,annotationClass = Mapper.class(示例 sb3)
  • 想用 @Repository → 需把老代码的 @Mapper 全部换成 @Repository, annotationClass = Repository.class(示例 sb2)

不能混用:@MapperScan(annotationClass=X) 只注册标注了 X 的接口,部分接口用 @Mapper、部分用 @Repository 时,另一种不会被注册(也不建议同时标注两个注解, 全工程应保持一种约定)。

说明:MyBatisGX 收集 DAO 的两处路径过滤条件不同(SqlSessionFactoryBeanPostProcessor 认 @Repository,MybatisgxContextLoader 认 @Mapper),但只要工程内注解统一, 两处路径总有一处能收集到,不会漏。