JQuickExcel 批量导入：用 importDataInBatch 控制大文件消费边界
tags: #JQuickExcel #JavaExcel #开源 #POI #Excel工具
简介
我处理大 Excel 导入时，最先消除的通常不是某一条 SQL，而是"解析完成后再统一处理"的全量集合。若一份文件有几十万行，应用同时保留 POI 工作簿、JQuickRow 列表、转换后的领域对象、校验错误和数据库批处理参数，堆使用会叠加。JQuickExcel 提供 JExcelImportHandler#importDataInBatch(JExcelImportModel, int, Predicate<List<JQuickRow>>)，使读取到的行可以按页交给业务代码消费。
本文只使用 README-CN、项目配置类和导入处理器中确认的 API：setBigFileImportEnabled、setImportBatchThreshold、importDataInBatch。我将说明批量 API 真正限制的对象范围、回调返回值的停止语义、末尾不足一页数据的处理，以及如何把数据库写入策略放在正确的边界上。文中的性能描述均为示例实验设计，必须在本机和目标环境复测，不是项目官方数据。
前言
"每 5,000 行一批"不是一条放之四海皆准的规则。批次过大时，一批内的 JQuickRow、DTO、校验信息和数据库参数都会变大；批次过小时，回调次数、事务提交和网络往返可能上升。我把批大小视为应用背压的一部分，而不是一个为了好看的常量。先根据单行对象大小、校验逻辑、数据库驱动限制、事务语义和并发任务数选定起点，再用可重复测试调整。
我也会区分两个层面。setBigFileImportEnabled(true) 控制输入流构造工作簿时优先走 OPCPackage.open 再创建 XSSFWorkbook 的路径，目的是改善工作簿打开阶段的峰值内存；importDataInBatch 则在解析数据行后，不让应用层把全部 JQuickRow 聚合到一个列表。前者不是 SAX 事件读取，也不会让完整工作簿结构消失；后者也不会替数据库自动提交事务。两者可以同时使用，但分别解决不同的资源问题。
项目中的 setImportBatchThreshold 是"建议阈值"，并不把 importData 自动改写为批量回调。我的代码会显式调用 importDataInBatch，使读取边界一眼可见。若仍调用全量 importData，即使设置了建议阈值，也仍会返回完整 List<JQuickRow>。这一点在故障排查时很重要：我不会只打印配置，而会确认实际调用的方法。
环境与依赖
本文以项目当前 Maven 坐标和 Java 8+ 运行环境为基础。项目 pom.xml 已声明 poi 与 poi-ooxml，使用 JQuickExcel 的导入处理器时不需要额外引入另一套 Excel 库。实际服务中我会锁定依赖版本，并避免上传接口、病毒扫描、对象存储和数据库批写使用互不兼容的流管理方式。
xml
<dependency>
<groupId>io.github.paohaijiao</groupId>
<artifactId>jquick-excel</artifactId>
<version>3.6.0</version>
</dependency>XML 负责声明导入的工作表、是否有表头、表头到字段的映射以及转换规则。批量消费不需要复制 XML；它使用同一个 JExcelImportModel，因此 SHEET、HEADER、MAPPING、TRANSFORM 和校验仍在读取批次之前生效。下面的写法采用 README-CN 已确认的 XML 服务格式。
xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE excels PUBLIC "-//PAOHAIJIAO//DTD API EXCEL 1.0//EN"
"classpath:paohaijiao/dtd/Jquick-excel.dtd">
<excels namespace="com.github.paohaijiao.xml.service.JQuickExcelExportService">
<excel name="importExcel" returnClass="java.util.List">
<![CDATA[
IMPORT WITH
SHEET="Customers",
HEADER=true,
MAPPING={"客户编号":"customerNo","姓名":"name","手机号":"mobile","注册日期":"registeredAt"},
TRANSFORM={"name":toUpper(${name})}
]]>
</excel>
</excels>我会让批量导入使用与该 XML 语义一致的 JExcelImportModel。具体模型通常由已有解析链路构建；本文不虚构新的工厂方法或 XML 参数。核心约束是：表头、映射和转换应在导入模型中稳定定义，业务回调拿到的 JQuickRow key 才能与普通导入一致。若模板发生变化，我先修正映射和校验，而不是在回调中按列下标临时猜测字段。
代码示例
下面先配置大文件导入相关选项。20,000 是项目默认建议阈值的同类示例，不是批量 API 的页大小；真正传给 importDataInBatch 的页大小在调用处明确写出。样式缓存与导入批次没有直接关系，但可作为进程统一配置的一部分保留。
java
import com.github.paohaijiao.config.JQuickExcelConfig;
JQuickExcelConfig.getInstance()
.setBigFileImportEnabled(true)
.setImportBatchThreshold(20_000)
.setCellStyleCacheEnabled(true);批量 API 的 consumer 是 Predicate<List<JQuickRow>>。回调返回 true 表示继续下一批，返回 false 表示在当前批完成后停止读取。该 API 返回已读取的非空数据行数；在提前停止场景，它反映停止前已经计入的行数。因此我会把"已读取""已成功入库""已拒绝"分开计数，不能把返回值直接当成最终成功条数。
java
import com.github.paohaijiao.handler.JExcelImportHandler;
import com.github.paohaijiao.model.JExcelImportModel;
import com.github.paohaijiao.statement.JQuickRow;
import java.io.InputStream;
import java.util.List;
public int importCustomers(InputStream input, JExcelImportModel model) throws Exception {
try (InputStream stream = input) {
JExcelImportHandler handler = new JExcelImportHandler(stream);
return handler.importDataInBatch(model, 5_000, batch -> {
persistBatch(batch);
return true;
});
}
}
private void persistBatch(List<JQuickRow> batch) {
// 将本批 JQuickRow 转换并同步持久化。
}在真实业务里，我会在同一个回调中完成本批转换、校验汇总和同步写入。把 batch 原样提交到无界线程池、立即返回 true，看起来像异步提速，实际上会移除读取端背压：解析速度可能超过数据库速度，待处理批次再次堆积为内存问题。需要异步时，我会使用有界队列并等待容量，或者复制数据并建立明确的完成与失败协议；如果没有这样的协议，就保持同步消费最容易判断资源上限。
提前停止示例也应明确保留上下文。下例以累计业务错误数为判定条件，回调返回 false 只会停止后续读取，不会回滚先前已经完成的动作。是否要回滚、是否允许部分成功，属于导入业务契约，必须在接口设计中说明。
java
AtomicInteger invalidRows = new AtomicInteger();
int read = handler.importDataInBatch(model, 1_000, batch -> {
List<JQuickRow> validRows = validateAndCollect(batch, invalidRows);
persistBatch(validRows);
return invalidRows.get() < 100;
});我会保证 pageSize 大于零。实现会对小于等于零直接抛出 IllegalArgumentException，因此不能把未校验的请求参数直接传入。对于首轮压测，我常从 1,000、2,000、5,000 三个值开始，固定同一份输入、同一 JVM 参数和相同数据库状态，分别记录端到端耗时、GC、每批耗时和失败恢复成本。所有所得数字都应标注为示例实验并要求本机复测。
原理说明
现有实现先设置目标 Sheet 并应用校验，然后读取有效列数。若模型声明有表头，首行单元格会经数据格式化后参与 MAPPING，未映射的表头保持原名；若没有表头，代码为列生成从 A 开始的字段名。随后从数据起始行逐行读取，按列构建 JQuickRow，对已配置的字段执行转换。非空行才会加入当前 batch，同时增加 totalRead。
当 batch.size() 达到 pageSize 时，实现调用 consumer.test(batch)，随后重新创建一个新的 ArrayList<>(pageSize)。这意味着回调所拿到的列表在实现层不会被后续批次填充，但业务代码仍应把它视为只在当前回调内有效的数据载体。循环结束后，若最后一批非空，即使不足 pageSize 也会调用一次消费者。这个末尾回调是我测试导入的必测项：例如 5,001 行、页大小 5,000，应该看到一批 5,000 行和一批 1 行，而不是遗漏最后一行。
消费者返回 false 时，实现会在当前满批处理后跳出循环。这里有一个边界需要理解：最后的 if (!batch.isEmpty()) 仍会检查当前新建或剩余的批次，因此我的回调必须具备幂等或清晰的状态控制，不会因为"以为停止后绝无再次调用"而写出不安全逻辑。正常实践是让每次回调都按批次标识记录结果，并在发生业务终止时统一报告，而不是依赖隐式流程猜测。
setBigFileImportEnabled(true) 的构造路径会尝试 OPCPackage.open(inputStream) 与 new XSSFWorkbook(pkg)；若失败则回退到 new XSSFWorkbook(inputStream)。它是降低工作簿打开峰值的一项策略，不改变 importDataInBatch 的分页语义。由于 XSSFWorkbook 仍需解析 xlsx 内部结构，极大共享字符串表、多 Sheet、复杂公式、图片或异常格式仍可能带来资源压力。我不会把它宣传成"任意大文件零内存导入"。
一次可复现的示例实验可以这样定义：固定 10 万行、5 列、固定随机种子和字段长度；运行 pageSize 为 1,000、2,000、5,000 的批量消费；数据库写入替换为确定的同步模拟或独立测量；记录读取总数、每批耗时分位、最大堆、GC 暂停和总耗时。只有在相同硬件、JDK、堆、文件和并发度下，比较页大小才有意义。结果只能写成该环境的示例，不得杜撰为 JQuickExcel 的官方吞吐量。
注意事项
setImportBatchThreshold只是建议阈值；要得到分页消费，必须显式调用importDataInBatch。pageSize必须大于零。我的应用配置会在进入处理器前校验，避免上传请求因非法参数中断。- 回调返回
true才会继续读取，返回false表示提前停止；我会单独记录已读、已成功和已失败行数。 - 最后一批不足页大小的数据也会回调。测试样本必须覆盖刚好整页、整页加一行和空数据三种边界。
- 回调中不要把
batch无限制异步堆积。同步处理，或使用有界并发和明确等待，才能维持背压。 - 数据库批大小不必等于 Excel 页大小。数据库驱动参数、索引成本和事务时间可能要求更小的分段。
- 文件级全量原子事务与超大文件分批提交往往冲突。我会在产品规则中明确是允许部分成功、写暂存表后统一提交，还是遇错即停止。
- 错误明细本身也要控制内存。大量错误应分页持久化或写入受控存储，不要在 JVM 中再累积几十万条异常对象。
setBigFileImportEnabled(true)改善的是工作簿打开策略，不代表完全事件流解析；仍要评估复杂 xlsx 的结构成本。- 所有性能数据只能作为示例实验。批次大小必须在本机、目标数据库和目标并发下复测。
总结
大文件导入的关键是让对象、批次和业务消费都有清晰边界。大文件打开选项只影响工作簿打开策略，importDataInBatch 才限定当前传给消费者的行集合；事务范围、数据库批量写入、错误明细保存和异步队列仍由应用控制。页大小不存在通用最优值，合适的数值取决于单行大小、转换成本、持久化吞吐和可接受的失败处理方式。
验收应覆盖整页、末页不足一批、空文件和提前停止等边界，同时分别核对已读取、已成功、已拒绝的数量。需要调整页大小时，在本机使用真实模板和目标数据库参数复测，观察批次耗时、GC、堆峰值及回压是否生效；结果应随配置快照保存。只有文件结构、映射和落库语义均正确时，性能记录才有参考价值。