MyBatis-Plus saveBatch批量插入性能优化与实战避坑指南

1. 从单条插入到批量入库：为什么saveBatch值得深究

在任何一个涉及数据库操作的后端项目里，数据插入都是最基础也最高频的动作。刚开始做项目时，我们可能习惯性地用save方法，一条一条地把数据往数据库里塞。这在小数据量、低频次的场景下没什么问题，但当你要处理一个包含上千条记录的Excel导入，或者一个实时流中不断涌来的数据点时，这种“单打独斗”的方式就会立刻成为性能瓶颈。我见过不少项目，在数据量稍微起来之后，导入功能就慢得让人无法忍受，甚至直接把数据库连接池打满，导致服务不可用。问题的根源，往往就出在最简单的“插入”操作上。

MyBatis-Plus（简称MP）作为MyBatis的增强工具包，其saveBatch方法就是为解决这个问题而生的。但如果你认为它只是简单地把多个save方法调用包在一个循环里，那就大错特错了。真正“玩转”saveBatch，意味着你需要理解它背后的批量提交（Batch）机制、事务边界、以及在不同场景下的性能表现和潜在陷阱。这不仅仅是调用一个API那么简单，而是涉及到JDBC驱动行为、数据库连接配置、以及MP自身封装逻辑的一整套知识。处理得当，它能将插入性能提升几个数量级；使用不当，它可能比单条插入还要慢，甚至引发数据一致性问题。

这篇文章，我就结合自己多次在数据同步、日志归档、批量初始化等场景中踩过的坑和积累的经验，带你彻底拆解saveBatch方法。我们会从它的默认行为聊起，深入到源码层面看它如何工作，然后探讨如何通过配置最大化其性能，最后分享几个实战中高频出现的“坑”及其解决方案。目标很明确：让你不仅能“用”saveBatch，更能“用好”它，在面对海量数据操作时心里有底，手上有招。

2. saveBatch的默认行为与底层机制拆解

很多开发者第一次使用saveBatch时，会下意识地认为它对应着SQL中的INSERT INTO table VALUES (…), (…), (…)这种多值插入语句。实际上，在默认配置下，MP的saveBatch并非如此。理解这一点，是避免后续很多误区的关键。

2.1 默认模式：模拟批量与JDBC批处理

MP的saveBatch方法，在默认情况下，其内部逻辑可以概括为“模拟批量”。当你传入一个实体列表（例如List<User>）时，MP会开启一个事务（如果当前没有事务），然后遍历这个列表。对于列表中的每一个实体，它会动态生成一条完整的INSERT语句（例如INSERT INTO user (id, name) VALUES (?, ?)），并通过MyBatis的SqlSession去执行。

这里的关键在于，MP默认会利用JDBC的PreparedStatement.addBatch()和executeBatch()机制。也就是说，对于每一条INSERT语句，MP会将其添加到同一个PreparedStatement的批处理队列中，而不是立即执行。当累积的语句数量达到一个阈值（这个阈值我们后面会详细讲），或者遍历完所有实体后，MP会一次性调用executeBatch()，将这批INSERT语句发送给数据库执行，然后清空批处理队列。

所以，数据库接收到的并不是一条包含多组值的SQL，而是多条独立的INSERT语句，只不过它们被JDBC驱动打包在一个网络请求里发送，并在数据库端作为一个批次执行。这相比循环调用save（每条语句独立请求、独立执行）已经带来了巨大的性能提升，主要体现在：

1. 减少网络往返（RTT）：多次单条插入需要多次完整的“请求-响应”网络交互，而批处理将多个操作合并，极大减少了网络延迟开销。
2. 数据库优化：大多数数据库（如MySQL、PostgreSQL）对批处理执行有内部优化，虽然是一条条执行，但上下文切换开销更小。

你可以通过开启MyBatis的SQL日志来验证这一点。默认情况下，你会看到多条INSERT语句被打印出来，但它们通常是在一个JDBC Batch的上下文中执行的。

2.2 一个容易被忽略的核心参数：batchSize

saveBatch方法有一个重载版本：saveBatch(Collection<T> entityList, int batchSize)。这里的batchSize参数至关重要，它直接决定了上面提到的“阈值”。

这个batchSize是什么意思？它并不是指一次向数据库插入多少条数据记录，而是指一次executeBatch()调用执行多少条SQL语句。在默认的“模拟批量”模式下，一条数据记录对应一条INSERT语句，所以batchSize在这里等价于“每批插入的记录数”。

MP的默认batchSize值是1000（在DbConfig中可配置）。这意味着，如果你传入一个3000条记录的列表，MP会将其分成3批，每批1000条，依次执行executeBatch()。

为什么需要分批？

1. 防止内存溢出（OOM）：PreparedStatement的批处理队列是在JVM内存中维护的。如果一次性将数万条语句加入批处理，会占用大量内存，可能引发OOM。
2. 避免超时与锁竞争：一个包含数万条INSERT的巨型批处理，执行时间会非常长。这可能导致数据库连接占用过久，增加锁等待时间，甚至触发事务超时。
3. 数据库限制：某些数据库的驱动或服务端对单次批处理的语句数量有限制。

因此，设置一个合理的batchSize是性能调优的第一步。对于大多数OLTP场景，1000是一个比较安全的默认值。但对于数据迁移、归档等场景，你可能需要根据实际情况调整。

注意：batchSize调得过大（比如10000）可能适得其反，导致单批执行时间过长，内存压力增大。通常建议在500-2000之间进行测试，找到最适合当前数据库和网络环境的甜蜜点。

2.3 与真正的批量插入（Bulk Insert）的对比

我们常说的“批量插入”在SQL层面有两种形式：

1. 多值插入（Multi-Value Insert）：INSERT INTO table (col1, col2) VALUES (v1, v2), (v3, v4), (v5, v6)...
2. JDBC批处理（Batch Insert）：多次INSERT INTO table (col1, col2) VALUES (?, ?)，然后通过addBatch()和executeBatch()执行。

MP默认的saveBatch采用的是第二种方式。第一种方式（多值插入）在插入大量数据时，理论上性能更高，因为SQL解析、执行计划生成的次数更少。MP本身不直接生成多值插入的SQL，但我们可以通过其他方式实现，这会在后面的高级用法中探讨。

这里先明确一个结论：在默认配置下，saveBatch的性能提升主要来自于JDBC批处理对网络和数据库执行的优化，而非生成更高效的SQL语句。它的优势在于通用性和无侵入性，对数据库和SQL语法没有特殊要求。

3. 深入配置：让saveBatch性能飞起来

理解了默认行为，我们就可以通过配置来解锁saveBatch的更强性能。这些配置分散在MP的全局配置、数据源配置以及数据库驱动层面。

3.1 关键配置参数解析

要让JDBC批处理发挥最大效力，以下几个参数必须关注：

1. MyBatis-Plus 全局配置 (MybatisPlusProperties或MybatisConfiguration)

• defaultBatchSize: 可以修改全局默认的批处理大小。在配置类中通过@Bean注入SqlSessionFactory时设置。

  @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); // ... 添加其他插件 return interceptor; } @Bean public ConfigurationCustomizer configurationCustomizer() { return configuration -> configuration.setDefaultBatchSize(500); // 修改默认批次大小 }

2. 数据源连接池配置 (如 HikariCP)批处理性能与数据库连接密切相关。务必在连接池配置中开启对批处理的支持：

• rewriteBatchedStatements=true(MySQL驱动最关键参数): 这个参数是MySQL JDBC驱动 (mysql-connector-java) 的。当设置为true时，驱动会尝试将executeBatch()中的多条INSERT语句重写为一条多值插入语句（即上面提到的第一种方式）。这是让MySQL下saveBatch性能产生质变的神奇参数！
  • URL示例：jdbc:mysql://localhost:3306/test?rewriteBatchedStatements=true&useUnicode=true&characterEncoding=utf8&useSSL=false
  • 效果：原本INSERT INTO t (a) VALUES (1); INSERT INTO t (a) VALUES (2);会被重写为INSERT INTO t (a) VALUES (1),(2);，性能提升极为显著。
• cachePrepStmts=true&prepStmtCacheSize=250&prepStmtCacheSqlLimit=2048: 这些是MySQL驱动关于预编译语句缓存的参数。开启后，数据库会缓存预编译语句，避免同一批INSERT语句的重复编译开销，对批处理性能也有积极影响。

3. 数据库服务端配置确保数据库服务端允许接受大的数据包。对于MySQL，需要检查max_allowed_packet参数。如果一次批处理的数据总量超过了这个值，会导致错误。通常建议设置为256M或更高，具体根据单条数据大小和batchSize来估算。

-- 查看当前值 SHOW VARIABLES LIKE 'max_allowed_packet'; -- 临时设置（重启失效） SET GLOBAL max_allowed_packet = 256*1024*1024; -- 需要在配置文件中修改以永久生效

3.2 性能对比测试与参数调优建议

纸上得来终觉浅，我通过一个简单的测试来展示不同配置下的性能差异。测试场景：向一个简单的user表（id, name, age）中插入10万条数据。

调优建议总结：

1. 首要任务：无论如何，一定要在MySQL连接字符串中加上rewriteBatchedStatements=true。这是成本最低、收益最高的优化。
2. 调整batchSize：在添加了上述参数后，batchSize的影响会相对变小，但依然重要。可以从默认的1000开始，根据实际数据量和服务器性能，在500-2000之间微调。建议进行压测找到最佳值。
3. 配合连接池优化：同时设置cachePrepStmts等相关参数，形成组合拳。
4. 关注数据库侧：确保max_allowed_packet足够大。

实操心得：在一次历史数据迁移中，我使用了未优化的saveBatch（方案B），迁移500万数据花了近半小时。加上rewriteBatchedStatements=true后（方案C），同样的数据量只用了不到2分钟。这个参数的重要性怎么强调都不为过。

4. 事务、ID生成与并发场景下的陷阱

当你把saveBatch的性能调上去之后，接下来就要面对它在复杂场景下的稳定性和正确性问题。这里有几个常见的“坑”。

4.1 事务的边界与控制

saveBatch方法本身不开启事务。它依赖于外部的事务上下文。

• 如果外部没有事务：MP在saveBatch方法内部会为每一批（注意，是每一批，不是整个列表）的执行开启并提交一个事务。这意味着，如果插入3000条数据，分3批，每批1000条，那么会存在3个独立的事务。如果第二批插入失败，第一批已经提交的数据不会回滚，这可能导致数据不一致。
• 如果外部有事务（例如方法上标注了@Transactional）：那么整个saveBatch的所有批次操作都在同一个事务中。任何一批失败，整个事务回滚，所有数据都不会插入。这是通常我们期望的行为。

因此，最佳实践是：在调用saveBatch的业务方法上，显式添加@Transactional注解，确保数据操作的原子性。

@Service public class UserService { @Transactional(rollbackFor = Exception.class) // 显式声明事务 public void batchImportUsers(List<User> userList) { userService.saveBatch(userList, 1000); } }

坑点警示：我曾经遇到过在异步方法（如@Async）中调用saveBatch，但没有注意事务传播，导致部分数据插入后，异步线程异常使得数据只插入了一半。务必确保事务边界清晰。

4.2 主键ID生成策略的冲突

MP默认的主键生成策略是IdType.ASSIGN_ID（雪花算法）或IdType.AUTO（数据库自增）。这在saveBatch时需要注意：

• ASSIGN_ID (雪花算法)：MP会在Java代码层面为每一条记录的ID赋值，然后再执行插入。这对于saveBatch是友好的，因为所有ID在插入前就已确定，不会引发数据库侧的主键冲突。性能也最好。
• AUTO (数据库自增)：这依赖于数据库的自增字段（如MySQL的AUTO_INCREMENT）。在批处理插入时，即使使用rewriteBatchedStatements重写为多值插入，MySQL也只会为第一条记录生成一个自增ID，然后依次递增。这看起来没问题。但是，如果你在插入前，业务逻辑中已经依赖了实体对象的ID（例如，用ID作为关联其他数据的键），那么就会出问题，因为ID在插入前是null。

建议：在需要批量插入且后续逻辑可能依赖ID的场景，优先使用ASSIGN_ID（雪花算法）。如果必须用AUTO，请确保在数据完全插入成功后，再使用这些数据的ID。

4.3 并发调用与连接池耗尽

高并发场景下，多个线程同时调用saveBatch，每个批处理都会占用一个数据库连接直到该批执行完毕。如果batchSize很大或数据量很大，单个批处理执行时间较长，就可能导致连接池中的连接被迅速占满，新的请求需要等待，引发系统雪崩。

解决方案：

1. 控制并发度：对于后台批量任务，使用线程池并控制最大并发线程数。例如，通过ThreadPoolExecutor限制同时执行批量导入的线程数。
2. 优化单次处理量：不要一次性尝试用saveBatch处理百万级数据。应该将其拆分成多个小任务，分批次、分时段处理。可以使用分页查询源数据，然后循环调用saveBatch。
3. 监控与扩容：监控数据库连接池的使用情况（如HikariCP的activeConnections、idleConnections）。在压力大时，适当增加连接池最大连接数（maximumPoolSize），但这只是缓解，根本还是要优化单次批处理的效率和控制并发。

5. 超越saveBatch：更高阶的批量操作策略

当saveBatch加上rewriteBatchedStatements优化后，性能已经非常可观。但对于一些极端场景（如单次初始化亿级数据），我们还可以考虑更激进的方案。

5.1 使用MP的executeBatch与自定义SqlInjector

MP的saveBatch最终会调用SqlSession的flushStatements()来执行批处理。我们也可以直接获取SqlSession，手动控制批处理过程，实现更精细的控制，比如混合INSERT和UPDATE操作。

更高级的用法是自定义SqlInjector，为你的Mapper注入一个全新的批量插入方法。这个方法可以直接编写使用<foreach>标签的MyBatis XML映射文件，生成真正的多值插入SQL。这种方式绕过了JDBC批处理重写，直接生成最优SQL，理论上性能极限更高。但实现复杂度也更高，需要深入理解MP的扩展机制。

5.2 终极武器：数据库原生批量导入工具

如果数据量真的巨大（例如TB级别），任何在应用层进行的批量插入都可能不是最优解。此时应该考虑数据库的原生工具：

• MySQL:LOAD DATA INFILE命令。它可以从一个文本文件（如CSV）中高速加载数据到表中，速度远超任何SQL插入方式。应用层的职责变为生成格式正确的数据文件。
• PostgreSQL:COPY命令。
• 其他数据库：都有类似的批量加载工具。

操作流程通常是：

1. 应用将待插入数据生成一个标准格式（如CSV）的文件。
2. 应用或运维人员通过命令行、脚本或JDBC执行LOAD DATA INFILE ...语句。
3. 数据库直接从文件系统读取并加载数据。

这种方式的速度比应用层插入快一个数量级以上，是数据迁移、初始化等场景的终极解决方案。当然，它牺牲了部分灵活性和事务控制，需要额外的文件生成和清理步骤。

5.3 实战中的选择策略

如何选择这些方案？我的经验是：

1. 日常业务批量操作（千到十万级）：saveBatch+rewriteBatchedStatements=true+ 合理batchSize+ 事务控制。这是性价比最高、最通用的方案，能满足99%的场景。
2. 定期数据同步或归档（百万级）：在上述方案基础上，进行应用内分页分批。例如，从源分页查询，每页1000条，循环调用saveBatch。同时，可以考虑在业务低峰期执行，并监控数据库负载。
3. 历史数据迁移或初始化（千万级以上）：优先评估使用数据库原生工具（如LOAD DATA INFILE）。如果条件不允许（如无文件服务器权限），再考虑使用自定义SqlInjector生成多值插入SQL，并严格控制批次大小和并发。

最后，无论用哪种方式，一定要在预发布环境进行充分的性能测试和数据一致性验证。批量操作无小事，一次线上事故的代价远高于开发时多花的时间。我自己的习惯是，任何新的批量逻辑上线前，都会用生产数据的子集做一次全流程的压测和回归，确认性能和结果都符合预期。