JQuickExcel 大文件排障与调优：从实际路径定位 OOM、临时盘和慢任务

JQuickExcel 大文件排障与调优：从实际路径定位 OOM、临时盘和慢任务

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

简介

大 Excel 故障很少是"少开了一个性能开关"这么简单。一次导出失败可能来自全量源数据列表、未走流式的工作簿、需要随机访问的功能组合、临时目录写满、样式高基数或输出流未完整结束；一次导入失败可能来自复杂 xlsx 工作簿、全量 List<JQuickRow>、无界异步队列、过大的数据库事务或错误明细无限积累。调优之前，我先确认实际调用路径和正在增长的资源。

JQuickExcel 现有能力提供了明确的排查支点：JQuickExcelConfig 可以设置流式导出、窗口、阈值、临时文件压缩、大文件导入策略、批量建议阈值和样式缓存；JExcelImportHandler#importDataInBatch 可以限制应用侧一次持有的导入行。本篇只围绕这些 README-CN、配置类和测试源码确认的 API 展开，不引入未经确认的配置项，也不杜撰任何官方性能数值。所有实验结论均应标记为示例实验，并在本机和目标环境复测。

前言

我不会看到 OutOfMemoryError 就直接提高 -Xmx。更大的堆可能只是延迟故障，也可能掩盖全量集合、每行唯一样式或无背压异步消费等根因。同样，导出耗时变长也不必然说明 Java 代码变慢：临时文件压缩、磁盘空间不足、文件系统抖动、GC 停顿和网络输出都可能成为主因。先收集输入文件特征、配置快照、异常栈、GC/监控信息和临时目录状态，才能做出有证据的调整。

我的排查顺序固定为四步。第一步确认输入与功能边界，例如 Sheet 数、有效行列、公式、图片、合并区域、长文本、样式和是否含隐藏工作表。第二步确认实际代码路径，例如导出是否达到正阈值、是否因随机访问回退，导入是否真的调用批量 API。第三步定位增长资源：堆、样式对象、临时盘、数据库队列还是输出带宽。第四步只调整与证据对应的一项或一组参数，并用同一份输入复测。

在生产问题中，我还会保留"失败的原始输入"或经过合规脱敏后的等价夹具。只凭用户一句"100MB Excel 导不出来"无法稳定复现，因为 xlsx 是 ZIP 容器，文件大小不反映共享字符串、样式、图片和公式复杂度。合规要求不允许保留原文件时，至少应记录行数、列数、Sheet 数、最大单元格长度、日期与公式数量、样式类别和异常行位置。

环境与依赖

本文使用项目当前 Java 8+ 和 Maven 坐标。依赖层不是性能调优的首选入口，但我会先检查运行时实际加载的版本是否与构建一致，避免因为重复引入 Apache POI 或类路径冲突而出现难以解释的行为。JQuickExcel 的项目 pom.xml 已声明 POI 相关依赖。

<dependency>
    <groupId>io.github.paohaijiao</groupId>
    <artifactId>jquick-excel</artifactId>
    <version>3.6.0</version>
</dependency>

排障环境记录至少包括 JDK、JVM 启动参数、操作系统、CPU、内存、磁盘类型、临时目录路径与可用空间、服务并发、输入文件路径或散列、文件大小、Sheet 数和业务模板版本。我会把这些信息与异常栈放到同一事件记录中。这样后续对比"开发机正常、容器失败"时，可以快速看出是否是堆、临时盘或运行时版本差异，而不是盲目修改 DSL。

隔离导出问题时，我用最小的、但语法真实的 XML 服务定义作为对照。若最小映射正常，而加入样式、公式或转换后失败，排查方向就从基础写出转向具体功能组合。下面使用 README-CN 已确认的 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="exportExcel" returnClass="void">
        <![CDATA[
            EXPORT WITH
            SHEET="Probe",
            HEADER=true,
            MAPPING={"id":"编号","name":"名称","createdAt":"创建时间"},
            FORMAT={"createdAt":"yyyy-MM-dd"}
        ]]>
    </excel>
</excels>

我会以最小 XML、增加 STYLE、增加 FORMULAS、增加业务转换的顺序逐层复现，而不是一次性改十个配置。每一层都生成独立文件并检查是否能打开；这样可以确定问题是模板语义、随机访问需求、样式基数还是数据本身。

代码示例

下列配置是我的排查基线，用来让每个资源策略显式可见。数值只是实验起点，不是任何服务器的保证值。配置对象是全局单例，所以我在任务运行前完成设置，并避免在并发请求中临时切换。

import com.github.paohaijiao.config.JQuickExcelConfig;

JQuickExcelConfig.getInstance()
        .setStreamingExportEnabled(true)
        .setStreamingExportThreshold(5_000)
        .setStreamingRowAccessWindowSize(100)
        .setStreamingCompressTempFiles(true)
        .setBigFileImportEnabled(true)
        .setImportBatchThreshold(20_000)
        .setCellStyleCacheEnabled(true);

导出排障时，我会确保流式临时文件在成功和失败路径都能清理。JExcelExportHandler#dispose() 在实际工作簿为 SXSSF 时释放临时磁盘文件。这个调用并不能修复写出前的 OOM，但可以避免任务完成后临时目录残留持续侵蚀磁盘空间。

JExcelExportHandler handler = new JExcelExportHandler(model, rows);
try (OutputStream output = new FileOutputStream(outputFile)) {
    handler.getWorkBook().write(output);
} finally {
    handler.dispose();
}

导入大文件时，我使用明确的页大小调用批量 API，而不是依赖 setImportBatchThreshold 自动切换。下面的回调同步持久化当前批；若累计错误过多，返回 false 停止后续读取。已读条数、成功条数和错误条数应该分别记录。

try (InputStream input = new FileInputStream(inputFile)) {
    JExcelImportHandler handler = new JExcelImportHandler(input);
    AtomicInteger errors = new AtomicInteger();
    int read = handler.importDataInBatch(model, 5_000, batch -> {
        persistValidRows(batch, errors);
        return errors.get() < 100;
    });
    System.out.println("readRows=" + read);
}

当故障与并发导出有关时，我不会试图通过在每个请求里修改 JQuickExcelConfig 区分策略。全局配置会影响同一 JVM 中其他任务。更稳妥的做法是限制大任务并发、为大任务提供独立执行资源，或在部署层面拆分不同策略的服务。具体并发控制由应用框架负责，不应伪装成一个 Excel 参数。

对性能复测，我会写出完整实验条件。例如"示例实验：固定 10 万行、8 列、有限日期金额格式、同一 JDK、同一堆、同一 SSD，比较流式开关和窗口"；测试表必须醒目说明"需本机复测，非官方数据"。我不会在文档中填入未经运行的 MB、秒数或百分比，因为这些数字会在不同机器上制造错误预期。

原理说明

导出处理器的实际流式选择依赖三个条件：streamingExportEnabled 为真，streamingExportThreshold 为正，且传入数据列表大小大于等于阈值。满足后处理器创建 SXSSFWorkbook，使用配置的窗口和临时文件压缩选项；但若当前导出模型需要随机行访问，处理器会关闭本次流式路径并使用 XSSFWorkbook。因此当堆随行数线性增长时，我先验证行数是否达到阈值、阈值是否为正、是否存在导致随机访问的功能组合，而不是立即把窗口从 100 调成更小。

窗口表示内存中保留的最近行数。旧行刷出后无法像普通 XSSF 行那样任意回头修改。临时文件压缩则在 CPU 与磁盘空间之间取舍：压缩通常减少临时盘占用，但会带来计算成本。若故障是"磁盘写满"，我会检查临时目录位置、容量、权限、并发任务数和是否在 finally 中调用 dispose()；若故障是"CPU 高而磁盘富余"，才将压缩开关纳入对照实验。任何取舍只能依据目标环境复测。

导入构造器在 bigFileImportEnabled 为真时优先尝试 OPCPackage.open(inputStream) 并创建 XSSFWorkbook，失败后回退到普通构造。它可以改善打开大 xlsx 的内存表现，但并不把导入转换为 SAX 事件流。复杂共享字符串、多工作表、公式、图片和大单元格仍会影响工作簿解析资源。若导入 OOM，我会先确认是否在应用层调用了全量 importData，是否把上传文件复制为 byte[]，以及是否将每批数据转成更多长期存活对象。

importDataInBatch 对当前业务层的 JQuickRow 集合提供页边界。实现逐行构造数据，达到 pageSize 时调用消费者并新建下一批列表，末尾不足一页也会回调。它不替你管理数据库事务、异步队列或错误清单。若回调把每批都放进无界队列，内存问题只是从 List<JQuickRow> 转移到了队列；若每批事务过大，瓶颈可能在数据库锁、日志或参数限制。我的调优会分别观察解析速度和消费速度，建立真正的背压。

样式问题则看 cellStyleCacheEnabled 和模板的样式基数。该开关用于缓存等价的 CellStyle，配置类明确提到 POI 的 64,000 样式上限。若日期、金额、表头和状态只使用有限规则，缓存能够复用对象；若业务为每行生成独特颜色、格式、字体或边框，缓存无法创造等价性。此时应先收敛业务视觉规则，而不是只增加堆或关闭流式。

我将故障现象映射到资源方向：导出堆升高先查源数据列表与实际流式路径；临时盘升高查 SXSSF 临时目录、压缩和清理；样式异常查高基数 STYLE/FORMAT；导入堆升高查全量导入、byte[] 复制与异步队列；导入慢查工作簿复杂度、批次消费和数据库吞吐。这个映射不是替代证据，而是让每次排查先缩小范围。记录真实指标后，我一次只改一个变量并复测。

注意事项

1. 收集异常栈、输入文件特征、配置快照、JVM 参数、临时盘状态和 GC/监控证据后再调参；没有证据的调整难以复现。
2. setStreamingExportThreshold(0) 或负值会关闭自动流式切换，不是强制流式。先确认阈值为正且数据量达标。
3. 即使流式开关已开，随机访问需求也可能使导出回退到 XSSF；必须用真实 DSL 验证实际功能组合。
4. setStreamingRowAccessWindowSize 必须大于零。窗口是近期行的驻留数量，不是批量大小。
5. 流式导出会使用临时目录。检查权限、可用空间、并发任务数和 dispose()，不要只盯 JVM 堆。
6. setBigFileImportEnabled(true) 只是优化工作簿打开路径，不能代替 importDataInBatch 的应用层分页消费。
7. setImportBatchThreshold 只是建议值；真正的页大小来自 importDataInBatch(model, pageSize, consumer)。
8. 回调中不要无界异步积压 batch，错误明细也不要无限存入内存；两者都必须有受控存储与背压。
9. setCellStyleCacheEnabled(true) 只能复用等价样式。动态颜色、动态格式、动态字体会让样式基数持续增长。
10. 任何耗时、堆或文件大小对比都只能作为示例实验，必须在本机和目标环境复测，不能写成 JQuickExcel 官方数据。

总结

排查大文件故障应从实际执行路径和持续增长的资源入手。导出堆增长优先检查源数据是否全量滞留及是否真正走入流式路径；临时目录异常关注 SXSSF 文件、压缩和清理；样式问题回到动态 STYLE 或 FORMAT；导入侧则分别观察工作簿复杂度、当前批次、错误集合和消费队列。一次只调整一个变量，才能把现象与改动建立可信关联。

每次修复都应回到同一份受控夹具验证文件正确性、行数、格式、末尾批次和异常处理，再记录堆、GC、临时盘与消费速度。本机复测能够筛选配置方向，却不能直接代表生产容量；目标机器、真实模板、并发数和存储条件发生变化后必须重新复测。保留输入版本、配置和结果，可让后续回归定位到具体条件而非猜测。