JQuickExcel 批量导入：用 importDataInBatch 控制大文件消费边界

JQuickExcel 批量导入：用 importDataInBatch 控制大文件消费边界

tags: #JQuickExcel #JavaExcel #开源 #POI #Excel工具

更多示例: JQuick-Excel 官网示例 https://www.jquick.org/jquick-excel/#demo-formulas0005

简介

我处理大 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 库。实际服务中我会锁定依赖版本，并避免上传接口、病毒扫描、对象存储和数据库批写使用互不兼容的流管理方式。

<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 version="1.0" encoding="UTF-8"?><!DOCTYPEexcelsPUBLIC"-//PAOHAIJIAO//DTD API EXCEL 1.0//EN""classpath:paohaijiao/dtd/Jquick-excel.dtd"><excelsnamespace="com.github.paohaijiao.xml.service.JQuickExcelExportService"><excelname="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 参数。核心约束是：表头、映射和转换应在导入模型中稳定定义，业务回调拿到的JQuickRowkey 才能与普通导入一致。若模板发生变化，我先修正映射和校验，而不是在回调中按列下标临时猜测字段。

代码示例

下面先配置大文件导入相关选项。20,000 是项目默认建议阈值的同类示例，不是批量 API 的页大小；真正传给importDataInBatch的页大小在调用处明确写出。样式缓存与导入批次没有直接关系，但可作为进程统一配置的一部分保留。

importcom.github.paohaijiao.config.JQuickExcelConfig;JQuickExcelConfig.getInstance().setBigFileImportEnabled(true).setImportBatchThreshold(20_000).setCellStyleCacheEnabled(true);

批量 API 的consumer是Predicate<List<JQuickRow>>。回调返回true表示继续下一批，返回false表示在当前批完成后停止读取。该 API 返回已读取的非空数据行数；在提前停止场景，它反映停止前已经计入的行数。因此我会把“已读取”“已成功入库”“已拒绝”分开计数，不能把返回值直接当成最终成功条数。

importcom.github.paohaijiao.handler.JExcelImportHandler;importcom.github.paohaijiao.model.JExcelImportModel;importcom.github.paohaijiao.statement.JQuickRow;importjava.io.InputStream;importjava.util.List;publicintimportCustomers(InputStreaminput,JExcelImportModelmodel)throwsException{try(InputStreamstream=input){JExcelImportHandlerhandler=newJExcelImportHandler(stream);returnhandler.importDataInBatch(model,5_000,batch->{persistBatch(batch);returntrue;});}}privatevoidpersistBatch(List<JQuickRow>batch){// 将本批 JQuickRow 转换并同步持久化。}

在真实业务里，我会在同一个回调中完成本批转换、校验汇总和同步写入。把batch原样提交到无界线程池、立即返回true，看起来像异步提速，实际上会移除读取端背压：解析速度可能超过数据库速度，待处理批次再次堆积为内存问题。需要异步时，我会使用有界队列并等待容量，或者复制数据并建立明确的完成与失败协议；如果没有这样的协议，就保持同步消费最容易判断资源上限。

提前停止示例也应明确保留上下文。下例以累计业务错误数为判定条件，回调返回false只会停止后续读取，不会回滚先前已经完成的动作。是否要回滚、是否允许部分成功，属于导入业务契约，必须在接口设计中说明。

AtomicIntegerinvalidRows=newAtomicInteger();intread=handler.importDataInBatch(model,1_000,batch->{List<JQuickRow>validRows=validateAndCollect(batch,invalidRows);persistBatch(validRows);returninvalidRows.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 的官方吞吐量。

注意事项

1. setImportBatchThreshold只是建议阈值；要得到分页消费，必须显式调用importDataInBatch。
2. pageSize必须大于零。我的应用配置会在进入处理器前校验，避免上传请求因非法参数中断。
3. 回调返回true才会继续读取，返回false表示提前停止；我会单独记录已读、已成功和已失败行数。
4. 最后一批不足页大小的数据也会回调。测试样本必须覆盖刚好整页、整页加一行和空数据三种边界。
5. 回调中不要把batch无限制异步堆积。同步处理，或使用有界并发和明确等待，才能维持背压。
6. 数据库批大小不必等于 Excel 页大小。数据库驱动参数、索引成本和事务时间可能要求更小的分段。
7. 文件级全量原子事务与超大文件分批提交往往冲突。我会在产品规则中明确是允许部分成功、写暂存表后统一提交，还是遇错即停止。
8. 错误明细本身也要控制内存。大量错误应分页持久化或写入受控存储，不要在 JVM 中再累积几十万条异常对象。
9. setBigFileImportEnabled(true)改善的是工作簿打开策略，不代表完全事件流解析；仍要评估复杂 xlsx 的结构成本。
10. 所有性能数据只能作为示例实验。批次大小必须在本机、目标数据库和目标并发下复测。

总结

大文件导入的关键是让对象、批次和业务消费都有清晰边界。大文件打开选项只影响工作簿打开策略，importDataInBatch才限定当前传给消费者的行集合；事务范围、数据库批量写入、错误明细保存和异步队列仍由应用控制。页大小不存在通用最优值，合适的数值取决于单行大小、转换成本、持久化吞吐和可接受的失败处理方式。

验收应覆盖整页、末页不足一批、空文件和提前停止等边界，同时分别核对已读取、已成功、已拒绝的数量。需要调整页大小时，在本机使用真实模板和目标数据库参数复测，观察批次耗时、GC、堆峰值及回压是否生效；结果应随配置快照保存。只有文件结构、映射和落库语义均正确时，性能记录才有参考价值。