Mybatis-Plus saveBatch失效排查：从JDBC批处理到事务边界的深度解析

1. 问题现场：一次“静默”的批量插入失败

那天下午，我正在处理一个后台数据同步任务，需要将上游系统推送过来的近千条用户标签数据，一次性写入我们的核心数据库。这活儿听起来简单，不就是个批量插入嘛。我熟练地调用了 Mybatis-Plus 的saveBatch方法，看着控制台打印出“插入成功”的日志，心里还想着效率不错。直到前端同事反馈说数据没展示出来，我才意识到不对劲。

检查数据库，表里空空如也，只有零星几条手动测试时留下的记录。没有报错，没有异常，事务也正常提交了，但数据就是没进去。这种“静默失败”最让人头疼，它不像空指针那样直接崩掉给你看，而是悄无声息地吞掉了你的操作，留下一堆看似正常的假象。我遇到的正是Mybatis-Plus中saveBatch()方法失效的经典场景。这个问题，如果你没踩过坑，可能会觉得“批量保存怎么可能失效？框架不是都封装好了吗？”但事实上，由于配置、环境、甚至是框架版本和数据库驱动的细微差异，这个看似简单的方法背后藏着好几个“失效陷阱”。今天，我就把这几个坑和排查、解决的完整链路，掰开揉碎了讲清楚。

2. 失效根因一：SQL 语句未真正执行与 JDBC 批处理开关

首先，我们要理解saveBatch()在 Mybatis-Plus 里是怎么工作的。它并不是简单地把多条INSERT语句用分号连起来发出去。在默认配置下，它的底层逻辑是依赖于 JDBC 的PreparedStatement.addBatch()和executeBatch()机制来实现批量操作的。这个机制本身是为了提升性能，但它需要一个关键的开关来激活。

2.1 核心配置：rewriteBatchedStatements参数

这个开关就是 MySQL JDBC 连接 URL 中的一个关键参数：rewriteBatchedStatements。它的默认值是false。当它为false时，尽管你的代码调用了addBatch()，JDBC 驱动在底层可能并不会将这些操作合并发送，或者以某种低效的方式处理，在某些版本或环境下，甚至可能导致批量操作“失效”——即语句被组装但未真正执行到数据库。

为什么需要这个参数？没有rewriteBatchedStatements=true，JDBC 驱动对批量插入的处理可能是“模拟”的，即客户端还是逐条发送 SQL 语句到服务器，只是网络通信上做了一些优化包装。而设置为true后，驱动会真正重写 SQL 语句，将多条INSERT合并成一条INSERT INTO table (a,b,c) VALUES (1,2,3), (4,5,6)...这样的多值语句。这种方式的效率有数量级的提升，同时也是确保批量操作原子性（要么全成功，要么全失败）和可靠执行的关键。

如何配置？在你的application.yml或application.properties中，数据库连接配置应该像这样：

spring: datasource: url: jdbc:mysql://localhost:3306/your_database?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&rewriteBatchedStatements=true # 其他配置...

或者在 JDBC URL 中直接追加&rewriteBatchedStatements=true。

注意：这个参数对 MySQL 性能影响巨大，尤其是在批量插入场景下。我实测过一个插入 1000 条记录的案例，开启后耗时从约 2 秒降至 0.2 秒以内。所以，这不仅是解决“失效”的问题，更是性能优化的必选项。

2.2 验证配置是否生效

配置了不代表就一定生效。有时候因为配置文件的加载顺序、多数据源配置覆盖等问题，这个参数可能没被正确应用。一个简单的验证方法是，在开启数据库的通用查询日志（general log）后，执行一次saveBatch，观察数据库实际接收到的 SQL 语句。

如果看到的是多条独立的INSERT语句，说明rewriteBatchedStatements可能未生效或框架/驱动未使用批处理模式。如果看到的是一条包含多个VALUES的INSERT语句，则说明批处理已正确工作。

此外，还可以在代码中通过判断SqlStatement的执行类型来间接验证。但更直接的方式是看执行效果和日志。Mybatis-Plus 默认的日志级别下，如果你看到为每一条数据都打印了==> Preparing:和==> Parameters:，那很可能批处理没开启。真正的批处理日志通常只显示一条 Preparing 和一组整合的参数。

3. 失效根因二：事务边界与传播行为的“隐形墙”

这是我踩过最深的一个坑，也是最容易忽略的一点。saveBatch()方法本身不开启事务。它是否在一个有效的事务上下文中执行，完全取决于调用它的方法。

3.1 事务失效的经典场景：方法内部调用

考虑以下代码：

@Service public class UserServiceImpl implements UserService { @Autowired private UserMapper userMapper; public void syncUsers(List<User> userList) { // 假设这里有一些业务逻辑 processUsers(userList); // 然后调用批量保存 batchSaveUsers(userList); } @Transactional(rollbackFor = Exception.class) public void batchSaveUsers(List<User> userList) { userMapper.insertBatchSomeColumn(userList); // 或者使用 saveBatch } }

在syncUsers方法中直接调用batchSaveUsers，@Transactional注解会失效。这是因为 Spring 的 AOP 事务代理是基于动态代理实现的。当在同一个类中的一个非事务方法内部调用另一个事务方法时，调用的是this.batchSaveUsers()，而不是经过 Spring 代理增强后的方法，因此事务切面不会生效。

解决方案有两种：

1. 将事务方法移到另一个 Bean 中：这是最清晰的方式。

   @Service public class UserTransactionService { @Autowired private UserMapper userMapper; @Transactional(rollbackFor = Exception.class) public void batchSaveUsers(List<User> userList) { userMapper.insertBatchSomeColumn(userList); } } @Service public class UserServiceImpl implements UserService { @Autowired private UserTransactionService userTransactionService; public void syncUsers(List<User> userList) { processUsers(userList); userTransactionService.batchSaveUsers(userList); // 跨Bean调用，事务生效 } }

2. 在外部方法上添加@Transactional：如果整个syncUsers方法需要原子性，直接在它上面加注解。

   @Transactional(rollbackFor = Exception.class) public void syncUsers(List<User> userList) { processUsers(userList); // 此时 batchSaveUsers 方法上的 @Transactional 可以去掉，或者使用 REQUIRED 传播行为并入外部事务 batchSaveUsers(userList); }

3.2 事务传播行为与回滚

即使事务生效了，还要注意saveBatch的异常处理。默认情况下，saveBatch在遇到单条数据插入失败时（比如主键冲突、字段超长），会抛出异常并导致整个事务回滚。这符合大多数业务场景的预期。

但有一种边缘情况：如果你的数据量极大，一次性saveBatch可能超出数据库允许的单条 SQL 长度限制（由max_allowed_packet参数控制）。这时，Mybatis-Plus 内部会进行分批（batchSize 默认为 1000）。需要注意的是，这个分批是在同一个物理数据库连接和事务内进行的，但如果其中一批失败，已经执行成功的批次不会自动回滚，除非你捕获异常并手动处理，或者框架内部做了特殊处理（通常不会）。更安全的做法是自己在业务代码里根据合理的batchSize进行手动分批，并对每一批单独使用@Transactional，这样可以更精细地控制事务边界。

4. 失效根因三：字段映射、主键策略与实体状态

数据没进去，也可能是数据本身“有问题”，导致框架生成的 SQL 语句本身就是无效的，或者执行后影响行数为 0。

4.1 字段映射与数据库默认值

检查你的实体类字段与数据库表字段的映射关系。Mybatis-Plus 默认使用驼峰转下划线的命名策略。如果数据库字段名是user_name，实体字段是userName，这没问题。但如果数据库字段是username，实体字段是userName，可能就会因为映射失败而导致该字段值为null。如果该字段在数据库中有非空约束且无默认值，就会导致整条插入失败。

建议：使用@TableField注解显式指定映射关系，尤其是在字段名不一致时。

@TableField(value = "db_username") private String userName;

另外，注意实体类中基本数据类型的默认值。比如int status;默认是 0，如果你希望插入时使用数据库定义的默认值（比如 DEFAULT 1），需要做特殊处理。一种方法是将字段改为包装类型Integer status;并设置为null，另一种是使用@TableField(fill = FieldFill.INSERT)配合自定义的MetaObjectHandler来设置插入时的默认值。

4.2 主键策略冲突

这是另一个高频坑点。Mybatis-Plus 的saveBatch方法在插入前，会检查实体的主键。如果你的主键策略是ASSIGN_ID（雪花算法）或ASSIGN_UUID，并且实体主键字段为空，框架会自动填充主键值。这很好。

但是，如果你的策略是AUTO（数据库自增），而你在实体里手动设置了一个非空的主键值，那么插入时可能会因为主键冲突而失败。或者，你的数据库表主键是自增的，但你在实体类上配置的策略是INPUT，期望手动输入，却忘了赋值，导致主键为null或 0，插入也会失败。

排查步骤：

1. 确认@TableId注解的type属性与数据库主键实际生成方式一致。
2. 检查传入saveBatch的实体集合中，每个实体的主键字段值是否符合预期（是null等待填充，还是有值）。
3. 查看生成的 SQL 日志，看INSERT语句中是否包含了主键字段以及对应的值是什么。

4.3 实体状态与版本号（乐观锁）

如果你的实体使用了 Mybatis-Plus 的乐观锁功能（@Version注解），在调用saveBatch进行插入时，通常不会有什么问题，因为插入时版本号字段（通常为version）会被赋予初始值（默认是0）。

但需要警惕的是，如果你混用了saveBatch和updateBatchById，或者你的 List 中既包含了新实体（无id）也包含了从数据库查出来准备更新的旧实体（有id），那么saveBatch的行为会变成“保存或更新”。此时，对于有id的实体，它会执行UPDATE语句，而乐观锁字段version会在WHERE条件中起作用。如果此时该实体的version值与数据库当前值不一致，就会导致更新影响行数为0，从效果上看，这条数据的更新“失效”了。

所以，务必保证传入saveBatch的列表中的实体状态清晰：要么全是新对象（主键为空，用于插入），要么全是旧对象（主键有值，且知晓其最新状态，用于更新）。不要混用。对于批量更新，更推荐使用updateBatchById方法。

5. 失效根因四：框架版本、依赖冲突与超时设置

环境问题往往是最隐蔽的。

5.1 Mybatis-Plus 与 Mybatis 版本兼容性

查看你的pom.xml或build.gradle。Mybatis-Plus 严重依赖于特定版本的 Mybatis。如果版本不匹配，可能会导致一系列诡异的问题，包括但不限于批处理失效。

例如，Mybatis-Plus 3.5.x 通常要求 Mybatis 版本在 3.5.6 以上。你可以去 Mybatis-Plus 官方文档或其pom.xml中查看它声明的 Mybatis 依赖版本。使用mvn dependency:tree命令检查实际引入的 Mybatis 版本，确保没有其他依赖强制拉低了版本。

5.2 数据库驱动版本

JDBC 驱动的版本也至关重要。较老的 MySQL 驱动（比如 5.x 的某些版本）对rewriteBatchedStatements参数的支持可能不完善或有 bug。建议使用较新的驱动，例如 MySQL 8.x 对应的mysql-connector-java8.0.x 版本。

在 Spring Boot 项目中，通常通过指定spring-boot-starter-data-jdbc或spring-boot-starter-data-jpa的版本间接管理驱动版本，但最好显式声明以确保一致性。

<dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>8.0.33</version> <!-- 使用一个稳定的较新版本 --> <scope>runtime</scope> </dependency>

5.3 连接池配置与超时

批量操作耗时可能比单条插入长。如果连接池的超时时间设置过短，可能在批处理执行过程中，连接被回收，导致后续批次失败。

重点检查项（以 HikariCP 为例）：

• connection-timeout：获取连接的超时时间。对于批处理，这个值可以适当调大，比如 30 秒。
• max-lifetime和idle-timeout：连接的生命周期。确保不会在执行中途因为连接过期而中断。
• 最重要的是事务超时：如果你使用了@Transactional，可以设置@Transactional(timeout = 60)来为整个事务方法设置超时时间（单位秒），这个时间要预估得比批量操作的最大可能耗时更长。

5.4 全局配置与自定义注入器干扰

Mybatis-Plus 提供了丰富的全局配置（MybatisPlusProperties），比如global-config.db-config下的id-type（全局主键策略）、logic-delete-field（逻辑删除字段）等。如果这些全局配置与你的实体注解配置冲突，可能会产生意想不到的效果。

此外，如果你自定义了SqlInjector来扩展全局方法，需要确保你的自定义逻辑没有影响到insert相关方法的正常行为。一个错误的com.baomidou.mybatisplus.core.injector.methods.Insert方法注入可能会覆盖默认的批量插入逻辑。

6. 系统性排查链路与实战调试技巧

当问题发生时，不要盲目猜测，遵循一个系统的排查链路可以事半功倍。

6.1 第一步：开启最详细的日志

这是获取第一手信息的关键。在application.yml中配置以下日志级别：

logging: level: com.baomidou.mybatisplus: DEBUG # 查看MP框架自身的日志 com.your.mapper.package: DEBUG # 查看你的Mapper接口日志 org.apache.ibatis: TRACE # 查看Mybatis底层的SQL执行日志，包括参数绑定 java.sql.Connection: DEBUG # 查看JDBC连接和语句操作 java.sql.Statement: DEBUG # 查看Statement执行细节 java.sql.PreparedStatement: DEBUG # 查看PreparedStatement细节，对批处理尤为重要

执行你的saveBatch方法，观察控制台输出。你需要关注：

• SQL 语句是否被准备（Preparing）？
• 参数（Parameters）是如何绑定的？是逐条绑定还是一次性绑定了多组？
• 最终是否有“Executing batch”或类似的日志？执行后返回的更新计数（Update Count）是多少？

6.2 第二步：验证单条插入是否正常

写一个最简单的单元测试，不使用saveBatch，而是用insert方法插入一条数据。这可以快速隔离问题：如果单条插入也失败，那问题出在数据源配置、实体映射、表结构等更基础的地方。如果单条成功，那问题就聚焦在“批量”这个动作上。

6.3 第三步：缩小数据规模与简化场景

用一个极小的 List（比如只包含 2 条记录）进行测试。排除因为数据量过大导致的超时、内存或其他边界问题。同时，确保这 2 条数据是“干净”的，没有业务逻辑的干扰，比如字段校验、AOP 切面等。

6.4 第四步：使用 Mybatis-Plus 的executeBatch方法进行底层验证

saveBatch方法内部会调用SqlHelper.executeBatch。你可以尝试直接使用这个底层方法，看看是否有效。这有助于判断问题是出在 MP 的服务层封装，还是更底层的 Mybatis/JDBC。

// 获取当前会话的SqlSession SqlSession sqlSession = SqlHelper.sqlSessionBatch(entityClass); // 获取Mapper YourMapper mapper = sqlSession.getMapper(YourMapper.class); try { for (YourEntity entity : entityList) { mapper.insert(entity); } // 手动提交，如果开启了事务则由事务管理器控制 sqlSession.commit(); } finally { sqlSession.close(); }

如果这种方式能成功，说明问题可能出在 MP 的saveBatch实现与你特定环境或配置的交互上。如果也失败，那问题很可能在 Mybatis 配置或 JDBC 层。

6.5 第五步：网络抓包与数据库日志（终极手段）

如果以上步骤都无法定位，可以考虑更底层的手段。

• 数据库通用日志：如前所述，在数据库服务器上开启通用日志，直接查看接收到的 SQL 语句。这是最权威的证据。
• 网络抓包：在应用服务器上使用tcpdump或Wireshark抓取发往数据库端口的流量，分析 MySQL 协议包。这能告诉你客户端到底发送了什么。对于批处理，你可能会看到一个包含多组参数的COM_STMT_EXECUTE指令包（如果使用了预处理语句）。

7. 替代方案与最佳实践总结

在彻底解决saveBatch问题之后，我们不妨思考一下，除了用它，还有没有更优解？或者说，如何更安全地使用它？

7.1 手动分批控制

对于超大数据量的插入，我强烈推荐手动控制分批，而不是依赖 MP 内部默认的 1000 条一批。原因如下：

1. 可控的事务边界：你可以为每一批单独管理事务，一批失败不影响其他批，或者选择重试特定批次。
2. 避免超长SQL：自己控制批次大小（比如 500 条一批），可以确保生成的 SQL 不会超过max_allowed_packet限制。
3. 内存与性能平衡：一次性加载数万条数据到 List 再交给saveBatch，可能会占用大量内存。手动分批处理可以流式读取和处理数据。

示例代码：

@Transactional(rollbackFor = Exception.class, propagation = Propagation.REQUIRES_NEW) // 每批一个独立事务 public void batchInsertInChunks(List<Data> hugeList, int chunkSize) { List<List<Data>> chunks = ListUtils.partition(hugeList, chunkSize); // 使用Guava或Apache Commons for (List<Data> chunk : chunks) { try { yourService.saveBatch(chunk); // 调用原saveBatch } catch (Exception e) { // 记录失败批次，进行重试或补偿操作 log.error("批次插入失败，批次数据: {}", chunk, e); // 根据业务决定是抛异常回滚整个大事务，还是只记录错误继续下一批 // throw e; // 抛出异常会使当前独立事务回滚，但外层大事务可能不受影响（取决于传播行为） } } }

7.2 使用insertBatchSomeColumn方法（MP 扩展）

Mybatis-Plus 提供了一个insertBatchSomeColumn方法，它位于com.baomidou.mybatisplus.extension.injector.methods.InsertBatchSomeColumn中。这个方法需要你通过自定义SqlInjector注入到你的 BaseMapper 中。

它的一个特点是会忽略空字段，只插入非空字段。这在某些场景下有用，但也要注意，它可能不是你想要的“全字段插入”。使用前需明确其行为。

7.3 终极武器：JDBC 原生批处理或批量工具

如果追求极致的插入性能，并且数据模型简单，可以考虑绕过 Mybatis/Mybatis-Plus，直接使用 Spring 的JdbcTemplate.batchUpdate()或者原生的 JDBC 批处理。这样可以获得最直接的控制和最少的框架开销。

@Autowired private JdbcTemplate jdbcTemplate; public void superBatchInsert(List<Data> list) { String sql = "INSERT INTO your_table (col1, col2) VALUES (?, ?)"; jdbcTemplate.batchUpdate(sql, new BatchPreparedStatementSetter() { @Override public void setValues(PreparedStatement ps, int i) throws SQLException { Data data = list.get(i); ps.setString(1, data.getCol1()); ps.setInt(2, data.getCol2()); } @Override public int getBatchSize() { return list.size(); } }); }

最后，关于saveBatch失效，我的个人体会是，它很少是框架本身的 bug，绝大多数时候是“环境配置”和“使用姿势”的问题。排查时，一定要有耐心，从最基础的数据库连接配置（rewriteBatchedStatements）和事务上下文查起，然后逐步向上，检查实体映射、主键策略，最后再怀疑框架版本和环境依赖。建立一个清晰的排查心智图，下次再遇到类似问题，你就能快速定位，而不是在百度里漫无目的地搜索“mybatis-plus savebatch 失效”了。记住，日志是你的第一盏灯，单元测试是你的安全网，而理解底层原理（JDBC批处理、Spring AOP事务）则是你永不迷路的指南针。