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, PredicateListJQuickRow)使读取到的行可以按页交给业务代码消费。本文只使用 README-CN、项目配置类和导入处理器中确认的 APIsetBigFileImportEnabled、setImportBatchThreshold、importDataInBatch。我将说明批量 API 真正限制的对象范围、回调返回值的停止语义、末尾不足一页数据的处理以及如何把数据库写入策略放在正确的边界上。文中的性能描述均为示例实验设计必须在本机和目标环境复测不是项目官方数据。前言“每 5,000 行一批”不是一条放之四海皆准的规则。批次过大时一批内的JQuickRow、DTO、校验信息和数据库参数都会变大批次过小时回调次数、事务提交和网络往返可能上升。我把批大小视为应用背压的一部分而不是一个为了好看的常量。先根据单行对象大小、校验逻辑、数据库驱动限制、事务语义和并发任务数选定起点再用可重复测试调整。我也会区分两个层面。setBigFileImportEnabled(true)控制输入流构造工作簿时优先走OPCPackage.open再创建XSSFWorkbook的路径目的是改善工作簿打开阶段的峰值内存importDataInBatch则在解析数据行后不让应用层把全部JQuickRow聚合到一个列表。前者不是 SAX 事件读取也不会让完整工作簿结构消失后者也不会替数据库自动提交事务。两者可以同时使用但分别解决不同的资源问题。项目中的setImportBatchThreshold是“建议阈值”并不把importData自动改写为批量回调。我的代码会显式调用importDataInBatch使读取边界一眼可见。若仍调用全量importData即使设置了建议阈值也仍会返回完整ListJQuickRow。这一点在故障排查时很重要我不会只打印配置而会确认实际调用的方法。环境与依赖本文以项目当前 Maven 坐标和 Java 8 运行环境为基础。项目pom.xml已声明poi与poi-ooxml使用 JQuickExcel 的导入处理器时不需要额外引入另一套 Excel 库。实际服务中我会锁定依赖版本并避免上传接口、病毒扫描、对象存储和数据库批写使用互不兼容的流管理方式。dependencygroupIdio.github.paohaijiao/groupIdartifactIdjquick-excel/artifactIdversion3.6.0/version/dependencyXML 负责声明导入的工作表、是否有表头、表头到字段的映射以及转换规则。批量消费不需要复制 XML它使用同一个JExcelImportModel因此SHEET、HEADER、MAPPING、TRANSFORM和校验仍在读取批次之前生效。下面的写法采用 README-CN 已确认的 XML 服务格式。?xml version1.0 encodingUTF-8?!DOCTYPEexcelsPUBLIC-//PAOHAIJIAO//DTD API EXCEL 1.0//ENclasspath:paohaijiao/dtd/Jquick-excel.dtdexcelsnamespacecom.github.paohaijiao.xml.service.JQuickExcelExportServiceexcelnameimportExcelreturnClassjava.util.List![CDATA[ IMPORT WITH SHEETCustomers, HEADERtrue, 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是PredicateListJQuickRow。回调返回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(InputStreamstreaminput){JExcelImportHandlerhandlernewJExcelImportHandler(stream);returnhandler.importDataInBatch(model,5_000,batch-{persistBatch(batch);returntrue;});}}privatevoidpersistBatch(ListJQuickRowbatch){// 将本批 JQuickRow 转换并同步持久化。}在真实业务里我会在同一个回调中完成本批转换、校验汇总和同步写入。把batch原样提交到无界线程池、立即返回true看起来像异步提速实际上会移除读取端背压解析速度可能超过数据库速度待处理批次再次堆积为内存问题。需要异步时我会使用有界队列并等待容量或者复制数据并建立明确的完成与失败协议如果没有这样的协议就保持同步消费最容易判断资源上限。提前停止示例也应明确保留上下文。下例以累计业务错误数为判定条件回调返回false只会停止后续读取不会回滚先前已经完成的动作。是否要回滚、是否允许部分成功属于导入业务契约必须在接口设计中说明。AtomicIntegerinvalidRowsnewAtomicInteger();intreadhandler.importDataInBatch(model,1_000,batch-{ListJQuickRowvalidRowsvalidateAndCollect(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 的官方吞吐量。注意事项setImportBatchThreshold只是建议阈值要得到分页消费必须显式调用importDataInBatch。pageSize必须大于零。我的应用配置会在进入处理器前校验避免上传请求因非法参数中断。回调返回true才会继续读取返回false表示提前停止我会单独记录已读、已成功和已失败行数。最后一批不足页大小的数据也会回调。测试样本必须覆盖刚好整页、整页加一行和空数据三种边界。回调中不要把batch无限制异步堆积。同步处理或使用有界并发和明确等待才能维持背压。数据库批大小不必等于 Excel 页大小。数据库驱动参数、索引成本和事务时间可能要求更小的分段。文件级全量原子事务与超大文件分批提交往往冲突。我会在产品规则中明确是允许部分成功、写暂存表后统一提交还是遇错即停止。错误明细本身也要控制内存。大量错误应分页持久化或写入受控存储不要在 JVM 中再累积几十万条异常对象。setBigFileImportEnabled(true)改善的是工作簿打开策略不代表完全事件流解析仍要评估复杂 xlsx 的结构成本。所有性能数据只能作为示例实验。批次大小必须在本机、目标数据库和目标并发下复测。总结大文件导入的关键是让对象、批次和业务消费都有清晰边界。大文件打开选项只影响工作簿打开策略importDataInBatch才限定当前传给消费者的行集合事务范围、数据库批量写入、错误明细保存和异步队列仍由应用控制。页大小不存在通用最优值合适的数值取决于单行大小、转换成本、持久化吞吐和可接受的失败处理方式。验收应覆盖整页、末页不足一批、空文件和提前停止等边界同时分别核对已读取、已成功、已拒绝的数量。需要调整页大小时在本机使用真实模板和目标数据库参数复测观察批次耗时、GC、堆峰值及回压是否生效结果应随配置快照保存。只有文件结构、映射和落库语义均正确时性能记录才有参考价值。