@MybatisPlusTest自动插入报错排查：数据源、事务与SQL初始化

写Mapper层单测的时候，我一开始真的是被@MybatisPlusTest这个注解坑得够呛。明明业务代码在Spring Boot启动后跑得好好的，数据也能正常插入，换成@MybatisPlusTest一跑单元测试，自动插入就报错，而且错误乱七八糟：有Failed to configure a DataSource的，有Table doesn't exist的，还有BAD SQL GRAMMAR的。更烦的是，这些报错往往不是直接出现在你写的那条insert语句上，而是出现在Spring容器启动阶段、MyBatis的缓存清理阶段，甚至出现在某个@PostConstruct初始化逻辑里，堆栈绕来绕去，定位一张表的数据插入就能折腾一下午。

这篇内容就把@MybatisPlusTest自动插入报错这件事彻底拆开。我会先讲这个注解的加载机制和隔离边界，再说一次完整的排查链路，然后逐个列出我实测遇过的高频根因和修复方案，最后把TestNG、@PostConstruct、事务回滚这三个特别容易和它纠缠在一起的坑也一并说清楚。适合正在用Spring Boot + MyBatis-Plus写单元测试、被@MybatisPlusTest折腾过的同学，这段内容能让你少走不少弯路。

1. 两种典型报错现场：H2内存库与MySQL双环境对比

@MybatisPlusTest自动插入报错，绝大多数场景分两类。一类是测试环境用H2内存数据库，另一类是测试环境直接连真实的MySQL。两种环境的报错特征不一样，排查思路也完全不一样，放在一起对比看会非常直观。

1.1 H2环境下：建表脚本没执行，却已经调用了Mapper

H2内存库的特点是启动快、依赖轻，适合跑纯逻辑层的单测。但H2不会自动创建表结构，必须靠schema.sql或data.sql初始化。很多项目在application-test.yml里配置了：

spring: datasource: url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;MODE=MySQL driver-class-name: org.h2.Driver username: sa password: sql: init: schema-locations: classpath:db/schema-h2.sql >Caused by: org.h2.jdbc.JdbcSQLSyntaxErrorException: Table "USER" not found

如果你查看的表名是大写、小写、驼峰，H2在MySQL模式下对大小写敏感还有一套自己的规则，这又会叠加一层混乱。User实体映射的user表，在H2里可能就被解析成了"USER"，然后提示找不到。很多人在这个环节就开始怀疑实体类注解配错了，其实根本不是。

1.2 MySQL环境下：数据源绕过了测试配置，连上了生产库

第二类更危险。有些项目图省事，测试类里没单独指定数据源，@MybatisPlusTest直接使用了application.yml里的MySQL连接。虽然能连上，也能插入，但至少有三个隐患：

1. 测试数据写进真实表，跑完不清理，污染开发库；
2. 如果表的字段有唯一约束，第二次跑同样的测试用例直接报Duplicate entry；
3. 更隐蔽的是，如果连的是生产库，风险就不是报错这么简单了。

我见过一个案例是测试类里用了@MybatisPlusTest，但又继承了某个抽象基类，基类上标了@SpringBootTest。测试注解被继承后，加载的是完整应用上下文，而不是切片上下文。数据源自然就走到生产配置了。最后解决办法是删掉继承关系，或者把公共配置提取到独立工具类里，而不是通过测试类继承。

这两种环境在报错信息上有个明显区别：H2环境下多是JdbcSQLSyntaxErrorException、表不存在、语法不兼容；真实MySQL环境下多是主键冲突、唯一约束冲突、或者连接串相关异常。先确认当前测试走的是哪个数据源，再开始排错，能省掉一大半无效排查。

2. @MybatisPlusTest加载链路拆解：为什么自动插入会翻车

要彻底搞清楚自动插入为什么报错，必须先弄明白@MybatisPlusTest启动时到底加载了什么、跳过了什么。

2.1 这个注解到底加载了哪些Bean

@MybatisPlusTest本身是一个组合注解，核心元注解包含下面这些：

• @ExtendWith(SpringExtension.class)（JUnit 5场景下）
• @BootstrapWith(SpringBootTestContextBootstrapper.class)
• @AutoConfigureCache、@AutoConfigureMybatisPlus、@AutoConfigureTestDatabase等
• 标记@Transactional默认开启事务回滚

它本质上是一个@SpringBootTest的切片变体，只加载MyBatis-Plus相关的自动配置类，包括MybatisPlusAutoConfiguration、MybatisPlusLanguageDriverAutoConfiguration等。也就是说，容器里只有数据源、SqlSessionFactory、Mapper接口代理、TransactionManager这一层的东西。@Service、@Controller、@Component这些业务Bean默认不会被扫描，更不会注册进容器。

这设计本来很好，测试隔离性高、启动快。但代价是：一旦你的业务代码里出现了间接依赖，比如@PostConstruct里调用了Mapper，或者某个Bean在初始化阶段就要操作数据表，切片的上下文根本hold不住。

2.2 事务自动回滚的实现边界

@MybatisPlusTest默认自带事务，测试方法跑完数据自动回滚。这个“自动回滚”是依赖TestTransaction和事务管理器实现的。但注意，它只对通过PlatformTransactionManager管理的事务有效。

MyBatis-Plus底层拿到的是SqlSession，自动提交开关默认关闭，事务靠Spring的DataSourceTransactionManager来提交/回滚。只要测试方法里没有手动@Commit，也没有嵌套新事务，数据就不会落库。

但在实际项目里，我踩过几个回滚不生效的坑：

• Mapper接口的方法上贴了@Transactional(propagation = Propagation.REQUIRES_NEW)，一旦REQUIRES_NEW触发，内部事务就脱离了外部测试事务的管理，会独立提交，测试结束后的回滚根本管不到它。
• 代码里有直接调SqlSessionTemplate.getConnection().setAutoCommit(true)这种底层操作，自动提交一开，事务管理器后续的rollback也就失效了。
• 数据源配置了HikariCP的auto-commit初始值时如果设为true，同样会影响。

所以，“自动插入报错”表面上是SQL语法或数据源问题，底层却可能是事务边界没搞清楚。

2.3 缓存清理时的“二次插入”现象

还有一个很容易误导人的报错模式：堆栈出现在flushing cache and retry附近。这句话看着像是插入之后清一级缓存时出的问题，实际上是因为MyBatis执行insert时，会先进入一级缓存判断，然后在真正执行SQL之前，如果发现statement发生了变化或者批量操作没有结束，就会触发flush。如果前面有一条SQL已经写入了数据，但事务没有正确声明，后面再插入时主键冲突，此时清缓存重试反而掩盖了真正出错的那一步。

我在一个项目里遇到过这样的报错：

### Error flushing statements. Cause: com.mysql.jdbc.exceptions.jdbc4.MySQLIntegrityConstraintViolationException: Duplicate entry '12345' for key 'PRIMARY'

第一反应是主键重复。但查了一圈才发现，同一个测试方法里有两个Mapper方法，第一个方法通过@PostConstruct已经提前执行过一次插入，到了测试方法执行阶段又插入同一条id的数据，于是主键冲突。而这个@PostConstruct根本不在@MybatisPlusTest的设计预期里，它导致数据自动插入发生在容器初始化阶段，直接把这个锅甩给了“自动插入报错”这个现象。

3. 一次完整排查记录：从堆栈第一行到根因落锤

光说理论不够，这里记录一次我印象特别深的排查全过程。现象是：项目从H2切换到真实MySQL后，@MybatisPlusTest里的insert直接报错，堆栈如下：

java.lang.IllegalStateException: Failed to load ApplicationContext at org.springframework.test.context.cache.DefaultCacheAwareContextLoaderDelegate.loadContext at org.springframework.test.context.junit.jupiter.SpringExtension.postProcessTestInstance Caused by: java.lang.IllegalArgumentException: Property 'sqlSessionFactory' or 'sqlSessionTemplate' are required at org.mybatis.spring.SqlSessionTemplate.<init> Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'sqlSessionFactory' Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'dataSource' Caused by: org.springframework.boot.autoconfigure.jdbc.DataSourceProperties$DataSourceBeanCreationException: Failed to determine a suitable driver class

3.1 第一步：先判断是不是数据源配置没生效

Failed to determine a suitable driver class是无数据源配置的典型报错。当时测试类长这样：

@MybatisPlusTest class UserMapperTest { @Autowired private UserMapper userMapper; }

而测试资源目录下只有application-test.yml，类上却没有激活testprofile。@MybatisPlusTest不会自动加载application-test.yml，它只会加载默认的application.yml，如果默认配置里没有数据源，那就直接完蛋。

解决办法是在测试类上加@ActiveProfiles("test")。顺便也可以加上@AutoConfigureTestDatabase(replace = Replace.NONE)，避免测试框架尝试把数据源替换成内嵌数据库。

3.2 第二步：看SQL打印，是根本没执行还是执行了报错

数据源修好后，又出现新的现象：test方法内insert没报错，但事务提交时报错，堆栈里能看到MySQL的Table 'testdb.user' doesn't exist。

这时候光看堆栈已经不够了，得看SQL执行情况。在application-test.yml里打开SQL日志：

logging: level: com.example.project.mapper: debug

或者：

mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

开了日志之后发现，insert SQL确实打印出来了，表名和字段名都对，但MySQL里根本没有这张表。这就不是SQL问题了，而是schema没初始化。项目为了兼容H2和MySQL，建表语句分了两套，H2用的是db/schema-h2.sql，MySQL用的是db/schema-mysql.sql。测试环境切换后，spring.sql.init.schema-locations还指向H2的脚本，MySQL环境下执行那么一套VARCHAR、AUTO_INCREMENT的写法很容易不兼容。

3.3 第三步：用@Sql注解主动建表

确认根因后，最终采用的方式是在测试类直接指定初始化脚本：

@MybatisPlusTest @AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE) @ActiveProfiles("test") @Sql(scripts = "/db/schema-mysql.sql", executionPhase = Sql.ExecutionPhase.BEFORE_TEST_METHOD) class UserMapperTest { @Autowired private UserMapper userMapper; }

这里要特别注意：@Sql默认在测试方法之前执行，如果你有多个测试方法，每个方法前都会跑一遍DROP TABLE IF EXISTS + CREATE TABLE，确保数据干净。但代价是增加了测试耗时。

3.4 第四步：从“报错位置”反推真正出错的Mapper

有时候堆栈指向的类和真正出错的类不是同一个。比如报错堆栈在UserMapper.insert，但实际是RoleMapper在插入时先执行了某个schema校验。MyBatis-Plus在解析实体类时，会根据@TableName注解映射表，但这个映射和实际数据库表结构不一致时，insert生成的SQL里就会出现多余的字段。

我那次最终定位到的真正原因，是实体类里新增了一个数据库里还没有的字段，MyBatis-Plus默认按全字段插入，INSERT INTO user (id, name, email, new_column) VALUES (...)，而MySQL表里没new_column这一列，数据库直接报Unknown column。解决方式有几种：

• 在实体类新字段上加@TableField(exist = false)，告诉MyBatis-Plus这不是表字段；
• 用@TableField(insertStrategy = FieldStrategy.NEVER)，只影响插入策略；
• 或者同步数据库表结构。

这个排查路径看起来简单，但当时绕了很久，就是因为被堆栈顶部的flushing cache带偏了方向。所以给个建议：看到自动插入报错，先打开SQL日志确认“实际执行了什么SQL”，再确认“SQL执行在哪个环节失败”，最后才动手改代码。

4. 六个高频根因逐一拆解与修复配置

下面是这段时间里实测遇到过的报错根因汇总，按出现频率排序，每一条都有对应的修复方式。虽然不能覆盖所有项目，但基本能把@MybatisPlusTest自动插入报错的坑踩个七八成。

4.1 根因一：字段策略和主键策略不匹配

MyBatis-Plus的ID生成策略有三种常见配置：AUTO（数据库自增）、ASSIGN_ID（雪花算法）、INPUT（手动输入）。在@MybatisPlusTest场景下，经常出现的问题是：

• 实体类配置AUTO，但测试库表结构里主键不是自增列，导致insert报错；
• 实体类配置ASSIGN_ID，但实体主键字段类型是Long，雪花算法生成的ID超出某些MySQL表中int列的范围，直接报Data truncation: Out of range value；
• 批量插入时，ASSIGN_ID和AUTO混用，导致部分行主键为空。

我当时遇到的一个案例是团队内部约定统一用ASSIGN_ID，但表结构从另一个系统迁移过来时主键还是int。插入单条看不出问题，一旦批量插入，SnowflakeIdWorker生成的ID不稳定地超出范围。修复方式一般是在测试的数据准备阶段指定一个固定ID，或者在实体类主键上用@TableId(type = IdType.AUTO)。

4.2 根因二：批量插入方法不是MyBatis-Plus内置方法

MyBatis-Plus的BaseMapper默认没有insertBatchSomeColumn，这是MybatisPlusMethod扩展能力的一部分。如果你项目里有人引用了类似：

userMapper.insertBatchSomeColumn(userList);

但测试切片里没有配置对应的SQL注入器，运行时就报：

Invalid bound statement (not found): com.xxx.UserMapper.insertBatchSomeColumn

或者提示BindingException。此时需要在测试环境里通过@Import把自定义SQL注入器配置进来：

@MybatisPlusTest @Import(MybatisPlusConfig.class) class UserMapperTest { ... }

这里MybatisPlusConfig里定义MybatisPlusSqlInjector这个Bean，里面注册InsertBatchSomeColumn方法。不配置的话，测试里一调用批量插入就挂，而且报错信息很容易让人误以为SQL写错了。

4.3 根因三：@TableField映射的列名和数据库关键字冲突

这个坑很经典。实体类字段叫order、desc、group这类SQL关键字时，生成的insert SQL就是：

INSERT INTO user (id, order) VALUES (?, ?)

MySQL直接报语法错误。H2在MySQL模式下对关键字的容忍度略有差异，所以经常出现“H2环境下测试通过，切到MySQL就报错”的情况。修复方式有两种：

• 在实体类字段上显式指定别名：

@TableField("`order`") private String order;

• 或者在MyBatis-Plus配置里开启自动加反引号：

mybatis-plus: global-config: db-config: column-format: "`%s`"

后者影响全局，谨慎使用。

4.4 根因四：MapperScan配置没有覆盖测试切片

@MybatisPlusTest虽然会加载MyBatis-Plus自动配置，但它不会主动扫描所有Mapper接口。它只会注册测试类里@Autowired标注的Mapper，如果有多个Mapper之间相互依赖，或者MyBatis的一级缓存和延迟加载机制需要额外的Mapper，就可能在解析时出现Bean没找到。

最简单的修复方式是在测试类上显式指定扫描包：

@MybatisPlusTest @MapperScan("com.example.project.mapper") class UserMapperTest { ... }

或者用@MybatisPlusTest(scanBasePackages = "com.example.project.mapper")。如果项目Mapper分布在多个包，用@MapperScan逐个列出即可。

4.5 根因五：测试环境和生产环境用了同一套实体类配置

这个属于设计层面的问题。有些项目的实体类上直接写了数据库相关的@TableName、@TableField，如果没有通过抽象层隔离，测试环境一旦连了别的库，这些映射关系可能和H2自动建表逻辑完全不匹配。

推荐的做法是，在test目录下准备一套独立的实体类或单独的应用配置。如果复用同一套实体类，至少保证数据库表结构和H2的schema脚本完全一致。实体类里尽量少用数据库特有的类型，比如json、enum等，否则在H2下类型映射会很难看。

4.6 根因六：SQL初始化脚本执行时机太晚

除了@Sql注解，spring.sql.init.mode这个配置也经常坑人。Spring Boot 2.5之后SQL初始化默认只对嵌入式数据库生效，如果你用的是真实MySQL，需要显式设置：

spring: sql: init: mode: always

否则MySQL环境下根本不会执行建表脚本。但要注意，mode: always意味着每次应用上下文启动都会执行脚本，脚本里如果没有DROP TABLE IF EXISTS，第二次启动建表就会报Table already exists。

综合来看，遇到@MybatisPlusTest自动插入报错，不要急着改业务代码，先在测试环境里把下面三件事确认清楚：

1. 测试数据源到底是H2还是MySQL；
2. 建表脚本是否真的执行了，执行的是哪一份脚本；
3. SQL日志是否打印出了真正的插入语句。

这三个点确定了，问题基本就能定位到根因。

5. 和TestNG、@PostConstruct、事务注解纠缠的那些坑

热搜词里出现一批跟单元测试相关的关键词，其中testng、@PostConstruct、事务注解这三个是我在实践中确实踩过的，位置非常特殊，单独拉出来说。

5.1 TestNG和@MybatisPlusTest的兼容问题

如果项目里已经集成了TestNG，但测试类还在用@MybatisPlusTest，多半会出问题。原因很直接：@MybatisPlusTest默认的扩展机制是基于JUnit 5的@ExtendWith(SpringExtension.class)设计的，而TestNG有自己的测试生命周期管理方式，和Spring的测试上下文框架不是一套东西。

具体表现是：Spring容器能正常启动，Mapper能注入成功，但测试方法里的自动插入要么不执行，要么执行后事务不生效；更常见的现象是报IllegalStateException: Could not find SpringExtension。

可行的做法是：

• 如果团队用TestNG，那就不要用@MybatisPlusTest，改用@SpringBootTest+ 手动配置Mapper扫描的方式，或者直接用SpringJUnit4ClassRunner这种兼容运行器；
• 如果坚持用@MybatisPlusTest，那就把TestNG从测试依赖里隔离出去，给MyBatis-Plus相关测试单独用JUnit 5。

这里没有特别优雅的二合一方案。Spring官方测试框架的重心在JUnit和TestNG两者之间有取舍，@MybatisPlusTest显然选了JUnit 5。

5.2 @PostConstruct里执行insert，为什么报错

我遇到过一个很奇怪的现象：测试类里什么都没做，只是@Autowired了一个Mapper，但一启动测试报错，堆栈指向一个@PostConstruct方法，里面调用了另一个Mapper的insert。

原因在于：@MybatisPlusTest加载的Spring容器虽然没有业务Bean，如果你的测试类或者导入的配置类中存在@PostConstruct初始化方法，并且这个方法调用了Mapper，那么它会在容器启动阶段执行一次插入。此时如果事务管理器的初始化还没完成，或者DataSource代理还没完全就绪，自动插入就会出问题。

更常见的场景是配置类里的@PostConstruct：

@TestConfiguration public class TestDataInitializer { @Autowired private UserMapper userMapper; @PostConstruct public void initData() { userMapper.insert(new User(...)); } }

这种写法的本意是提前准备测试数据，但它忽略了@MybatisPlusTest的阶段划分。数据准备应该在测试方法内部完成，或者用@BeforeEach、@Sql、@TestDataPrepare这类明确命名的机制。@PostConstruct在容器初始化阶段执行的数据库插入，极容易在事务边界之外操作数据，测试结束后还可能不清理，造成下一轮测试数据残留。

5.3 事务注解在Mapper方法上的限制

@MybatisPlusTest会为测试方法套上一层事务，但这层事务并不影响Mapper方法上的事务注解。如果Mapper方法上写了：

@Transactional(propagation = Propagation.REQUIRES_NEW) int insertUser(User user);

那么该方法的插入操作会挂起外层事务，开启一个新事务。测试方法结束后，外层事务回滚，但已经提交的新事务不受影响，数据直接落库。

等下轮测试再跑，同样的数据又插入一次，如果数据库有唯一索引，必然报Duplicate entry或者主键冲突。

排查技巧：如果发现测试里执行insert没问题，但第二次运行测试就报错，优先怀疑Mapper方法上的独立事务注解。解决办法一般是：

• 测试用的Mapper接口单独拆一个出来，不标注事务相关注解；
• 或者测试类统一使用@Transactional并调整隔离级别；
• 或者在@BeforeEach里执行DELETE FROM user清理数据。

6. 让Mapper层测试少踩坑的实操习惯

最后这部分算不上什么高深理论，全是我自己试过之后总结出来的操作习惯，照着做能省不少排查时间。

6.1 测试类保持最小依赖，不继承业务基类

有段时间同事为了复用公共配置，在测试类上继承了一个业务BaseService，结果@MybatisPlusTest的切片配置被@SpringBootTest元注解覆盖，导致整个应用上下文全部加载，整个单元测试跑了将近一分钟。这已经完全失去了@MybatisPlusTest“只测Mapper”的意义。

所以测试类的继承结构要尽量扁平，公共配置写在src/test/java下的基础测试类里，只放数据源、SQL初始化、事务回滚这些测试专用配置，不要混入任何业务逻辑。

6.2 数据准备和断言分开

@MybatisPlusTest的定位是Mapper层测试，不是业务层测试。数据准备最好用两种方式之一：

• 固定SQL脚本，用@Sql注解挂在测试方法上；
• 测试方法内先delete，再insert，最后select断言。

我个人的习惯是：准备数据时不用被测Mapper自己的insert方法，因为这样万一insert方法本身有bug，用例根本测不出来。更稳妥的做法是单独写一个测试数据专用Mapper或在schema.sql里直接预置数据，让被测方法只负责自己的逻辑判断。

6.3 给测试数据源和业务数据源彻底分开

如果条件允许，每个开发者本地都在Docker里跑一个MySQL测试实例，连的库名统一叫testdb，建表脚本维护在src/test/resources/db下。这样既不依赖H2的兼容性问题，也不会有连到真实库的风险。测试完甚至可以直接用DROP TABLE清理，反正库里没有真实业务数据。

6.4 关注MyBatis-Plus和Spring Boot版本兼容性

版本问题虽然不直接算“自动插入报错”的根因，但它的影响非常隐蔽。比如MyBatis-Plus 3.4.x和3.5.x在批量插入的SQL注入器注册方式上就有差异，从3.5.x版本开始，自定义SQL注入器的包路径变了，测试切片里如果还按旧包名@Import，直接启动失败，报错却是No suitable driver，排查起来非常混淆。

建议在项目里统一管理版本，至少保证mybatis-plus-boot-starter和Spring Boot的兼容矩阵在官方文档范围内。不要一个升级一个不升级。

6.5 测试方法内主动开启SQL日志断言

打开MyBatis-Plus的SQL日志，然后断言SQL执行结果，这一步在排查阶段尤其重要。断言SQL可以用AssertJ或JUnit的assertThrows。比如你预期某个字段超长会导致插入失败，那就不要默默吞掉异常，而是明确断言它抛出了DataIntegrityViolationException。这样测试失败时才不会只看到一句“插入报错”，而是能看到具体原因。

@MybatisPlusTest自动插入报错的排查，说到底就是两个关键词：边界和顺序。边界是指测试切片的Bean范围，顺序是指SQL初始化、数据准备、Mapper执行、事务提交的先后关系。把这两个维度理清了，绝大多数报错都能快速归因。如果你也在某个奇奇怪怪的报错里卡了很久，先别改业务代码，从测试环境的数据源和SQL日志开始查起，大概率问题就出在那两个地方。