夜雨聆风
内容排版由AI整理
做后端导出，几乎绕不开 EasyExcel。但很多同学的使用方式一直停留在"一个 Excel 一个 Sheet、一次写完"的初级阶段。一旦产品提需求——"数据多了分 Sheet"、"按批次分文件打包成 ZIP"，就开始手忙脚乱地查文档。
这篇文章就从一个真实的积分发放明细导出场景出发，把 EasyExcel 在"一个 Excel 多 Sheet → 多个 Excel 多 Sheet → 多个 Excel 单 Sheet + ZIP"这条演进路径上的写法、坑点和最佳实践讲清楚。下一篇我们再聊线程池并行生成和复杂表头模板。
一、业务背景：从最朴素的导出说起
先看一下需求起点。有一个积分发放明细的导出接口，数据量可能从几千到几十万条不等，原始代码长这样：
private void asyncExportExcel(AssetIssueQueryIn signExportVO, String key, int totalCount) { EmCompanyVo company = getCompanyAndChild(signExportVO.getCompanyId()); String companyName = company.getCompanyName(); String fileName = companyName + "_积分发放明细"; File file = new File(fileName + ".xlsx"); String finalCompanyName = companyName; asyncTaskExecutePool.getAsyncExecutor().execute(() -> { Class<?> dtoClass = AssetIssueDetailExVo.class; ExcelWriter excelWriter = EasyExcel.write(file, dtoClass).build(); // 多线程分页查询 + 写入 processDataInParallel(signExportVO, totalCount, dtoClass, excelWriter, finalCompanyName); // 上传 OSS uploadToOssAndFinish(file, fileName, key); });}
processDataInParallel 用线程池并发分页查数据，每查完一页就写到一个 Sheet 里。看起来已经"多 Sheet"了，但它有几个问题：
1. Sheet 划分绑定在查询分页上：pageSize=5000，所以每个 Sheet 都是 5000 条2. 数据可能乱序：多线程查询的完成顺序不固定，写入 Sheet 的数据顺序可能和数据库里不一致3. 无法满足"每 1000 条换 Sheet"的需求
理解这个起点，后面的演进才有意义。
二、一个 Excel 多 Sheet：每 1000 条切一刀
第一个需求是：数据量超过 1000 条就换 Sheet，每个 Sheet 都有相同的表头。
原代码是按"查询分页"划分 Sheet，一页 5000 条。要改成"1000 条换 Sheet"，思路有两个：
思路 A：合并后再切分（推荐，最直观）
把多线程查回来的数据按页码顺序合并成一个大列表，再按 1000 条 subList 切分写入：
private void processDataInParallel(AssetIssueQueryIn vo, int totalCount, Class<?> dtoClass, ExcelWriter excelWriter, String companyName) { int pageSize = 5000; // 查询分页大小保持不变 int sheetSize = 1000; // 业务需求：每个 Sheet 1000 条 int totalPages = (totalCount + pageSize - 1) / pageSize; Map<Integer, List<AssetIssueDetailExVo>> dataMap = new ConcurrentHashMap<>(); CountDownLatch latch = new CountDownLatch(totalPages); // 第一步：并发查询（保证查询效率） for (int i = 1; i <= totalPages; i++) { int finalPageNum = i; asyncTaskExecutePool.getAsyncExecutor().execute(() -> { try { PageHelper.startPage(finalPageNum, pageSize); List<AssetIssueInfoDetail> details = assetDetailMapper.selectInfoPage(vo); if (!CollectionUtils.isEmpty(details)) { List<AssetIssueDetailExVo> infoList = ModelMapperUtils.convertList(details, AssetIssueDetailExVo.class); infoList.forEach(d -> { d.setIssuedStateText(d.getIssuedState() ? IssueStateEnum.two.getName() : IssueStateEnum.one.getName()); d.setInitialPoint(d.getInitialPoint().divide(new BigDecimal(100))); d.setCompanyName(companyName); }); dataMap.put(finalPageNum, infoList); } } finally { latch.countDown(); } }); } try { latch.await(); // 第二步：按页码顺序合并（并发查回来的 Map 顺序是乱的） List<AssetIssueDetailExVo> allData = new ArrayList<>(); for (int i = 1; i <= totalPages; i++) { if (dataMap.containsKey(i)) { allData.addAll(dataMap.get(i)); } } // 第三步：按 1000 条切分写入 Sheet if (!allData.isEmpty()) { int totalRecords = allData.size(); for (int i = 0; i < totalRecords; i += sheetSize) { int end = Math.min(i + sheetSize, totalRecords); List<AssetIssueDetailExVo> subList = allData.subList(i, end); int sheetNo = (i / sheetSize) + 1; WriteSheet writeSheet = EasyExcel.writerSheet(sheetNo - 1, "明细-第" + sheetNo + "页") .head(dtoClass) .build(); excelWriter.write(subList, writeSheet); } } if (excelWriter != null) { excelWriter.finish(); } } catch (Exception e) { logger.error("写入 Excel 异常", e); }}
这里有几个关键点：
1. dataMap 用 finalPageNum 做 Key：保证后续能按页码顺序合并，解决并发查回来的乱序问题2. subList(i, end) 切分：每 1000 条切一刀，end = Math.min(i + sheetSize, totalRecords) 处理最后一段不足 1000 的情况3. EasyExcel.writerSheet(sheetNo - 1, ...)：Sheet 索引从 0 开始，每次都传 .head(dtoClass) 保证表头一致4. excelWriter.finish() 必须在所有数据写完后调用：刷新缓冲区到磁盘，确保文件可安全上传
思路 B：偷懒方案（数据量小可用）
如果性能允许，最简单的办法是直接把 pageSize 改成 1000。这样原来的"一个分页一个 Sheet"逻辑自动就变成"每 1000 条一个 Sheet"，代码改动最小。
但代价是查询次数翻 5 倍，数据库压力增大，只适合数据量不大的场景。
三、多个 Excel 多个 Sheet：按字段分组打包 ZIP
第二个需求来了：按 batchNo（批次号）字段划分成多个 Excel 文件，每个 Excel 内部仍然多 Sheet，最后打包成 ZIP 上传 OSS。
数据组织维度从"数据 → Sheet"升级成"数据 → BatchNo(Excel) → Sheet"。需要引入 Java 的 ZipOutputStream 来处理压缩。
private void processDataToZip(AssetIssueQueryIn vo, int totalCount, File zipFile, String companyName) { int pageSize = 5000; int sheetSize = 1000; int totalPages = (totalCount + pageSize - 1) / pageSize; Map<Integer, List<AssetIssueDetailExVo>> dataMap = new ConcurrentHashMap<>(); CountDownLatch latch = new CountDownLatch(totalPages); // 1. 并行查询数据（逻辑同上，省略） // ... try { latch.await(); // 2. 按 batchNo 对所有数据进行分组 Map<String, List<AssetIssueDetailExVo>> batchGroup = dataMap.values().stream() .flatMap(List::stream) .collect(Collectors.groupingBy(AssetIssueDetailExVo::getBatchNo)); // 3. 创建 ZIP 输出流 try (ZipOutputStream zos = new ZipOutputStream(new FileOutputStream(zipFile))) { for (Map.Entry<String, List<AssetIssueDetailExVo>> entry : batchGroup.entrySet()) { String batchNo = entry.getKey(); List<AssetIssueDetailExVo> batchData = entry.getValue(); // 为每个 batchNo 创建内存中的 Excel ByteArrayOutputStream baos = new ByteArrayOutputStream(); ExcelWriter excelWriter = EasyExcel.write(baos, AssetIssueDetailExVo.class).build(); // 4. 在该 Excel 内部按 1000 条分 Sheet int batchTotal = batchData.size(); for (int i = 0; i < batchTotal; i += sheetSize) { int end = Math.min(i + sheetSize, batchTotal); List<AssetIssueDetailExVo> subList = batchData.subList(i, end); int sheetNo = (i / sheetSize) + 1; WriteSheet sheet = EasyExcel.writerSheet(sheetNo - 1, "Sheet" + sheetNo).build(); excelWriter.write(subList, sheet); } excelWriter.finish(); // 5. 将生成的 Excel 字节流写入 ZIP 实体 ZipEntry zipEntry = new ZipEntry("批次_" + batchNo + ".xlsx"); zos.putNextEntry(zipEntry); zos.write(baos.toByteArray()); zos.closeEntry(); } } } catch (Exception e) { throw new RuntimeException("生成 ZIP 文件失败", e); }}
这里的核心变化：
| 维度 | 实现方式 | 说明 ||------|---------|------|| 组织维度 | Map<String, List> | 用 Java 8 Stream 的 groupingBy 按 batchNo 实时分组 || 存储策略 | ByteArrayOutputStream | 不在磁盘产生临时文件，先在内存构建 Excel 再塞进 ZIP || Sheet 划分 | subList 步进 | 每个 Excel 内部仍按 1000 条切 Sheet || 资源释放 | try-with-resources | 确保 ZipOutputStream 正确关闭，避免文件损坏 |
一个内存警告：ByteArrayOutputStream + flatMap 归类在数据量极大（50 万条以上）时非常吃内存，建议改用临时文件（下一篇会讲）。
四、多个 Excel 单 Sheet：去掉 1000 条切分
需求又变了：每个 Excel 只需要一个 Sheet，不再按 1000 条切分。结构变得更扁平——"数据 → batchNo 分组 → 独立 Excel（单 Sheet）→ ZIP"。
既然每个 Excel 只有一个 Sheet，就不需要 for 循环和 subList 了，直接把整个批次数据一次性写入：
private void processDataToZip(AssetIssueQueryIn vo, int totalCount, File zipFile, String companyName) { int pageSize = 5000; int totalPages = (totalCount + pageSize - 1) / pageSize; Map<Integer, List<AssetIssueDetailExVo>> dataMap = new ConcurrentHashMap<>(); CountDownLatch latch = new CountDownLatch(totalPages); // 1. 并行查询数据（逻辑同上，省略） // ... try { latch.await(); // 2. 按 batchNo 分组 Map<String, List<AssetIssueDetailExVo>> batchGroup = dataMap.values().stream() .flatMap(List::stream) .collect(Collectors.groupingBy(AssetIssueDetailExVo::getBatchNo)); // 3. 创建 ZIP 输出流 try (ZipOutputStream zos = new ZipOutputStream(new FileOutputStream(zipFile))) { for (Map.Entry<String, List<AssetIssueDetailExVo>> entry : batchGroup.entrySet()) { String batchNo = entry.getKey(); List<AssetIssueDetailExVo> batchData = entry.getValue(); // 每个 batchNo 一个内存 Excel ByteArrayOutputStream baos = new ByteArrayOutputStream(); ExcelWriter excelWriter = EasyExcel.write(baos, AssetIssueDetailExVo.class).build(); // 4. 只创建一个 Sheet，一次性写入全部批次数据 WriteSheet sheet = EasyExcel.writerSheet(0, "发放明细").build(); excelWriter.write(batchData, sheet); excelWriter.finish(); // 5. 塞入 ZIP ZipEntry zipEntry = new ZipEntry("批次_" + batchNo + ".xlsx"); zos.putNextEntry(zipEntry); zos.write(baos.toByteArray()); zos.closeEntry(); } } } catch (Exception e) { throw new RuntimeException("生成 ZIP 文件失败", e); }}
这版的好处：
1. 逻辑极大简化：删掉了"序号计算"和"subList 分页截取"，excelWriter.write(batchData, sheet) 一步到位2. 每个 Excel 结构统一：内部只有一个叫"发放明细"的 Sheet3. 契合产品原型：导出的每个 Excel 格式完全一致，方便用户查看
五、EasyExcel 多 Sheet 写入的核心要点
回顾这条演进路径，有几个 EasyExcel 多 Sheet 写入的通用要点值得记住。
1. ExcelWriter 是有状态的，必须 finish()
ExcelWriter 内部维护着写入上下文，缓冲区里的数据要等 finish() 才会真正刷到文件/流里。忘记调 finish() 会导致生成的 Excel 损坏或为空。
try { // 多次 write ...} finally { if (excelWriter != null) { excelWriter.finish(); }}
2. WriteSheet 每次都要 .head(dtoClass)
如果希望每个 Sheet 都有相同的表头，创建 WriteSheet 时必须带上 .head(dtoClass)：
WriteSheet writeSheet = EasyExcel.writerSheet(sheetNo - 1, "明细-第" + sheetNo + "页") .head(dtoClass) // 关键：每个 Sheet 都生成表头 .build();
不带的话，后续 Sheet 会没有表头。
3. Sheet 索引从 0 开始
EasyExcel.writerSheet(sheetNo - 1, ...) 的第一个参数是 Sheet 索引，从 0 开始。算 Sheet 编号时要减 1，避免越界。
4. 并发查询的乱序问题
多线程查回来的数据放进 ConcurrentHashMap 时，必须用页码做 Key，后续按页码顺序合并，否则 Sheet 里的数据顺序会和数据库不一致。这是个隐蔽但致命的 bug——数据能导出，但顺序是乱的。
5. ZipOutputStream 不是线程安全的
ZipOutputStream 不能让多线程并发 write，否则压缩包会损坏。所以 ZIP 的写入必须放在主线程串行执行。下一篇讲线程池并行生成 Excel 时会专门强调这一点。
六、演进路径总结
把这一篇的核心演进路径梳理成一张表：
| 阶段 | 数据组织 | Sheet 划分 | 输出形式 | 适用场景 ||------|---------|-----------|---------|---------|| 起步 | 数据 → Sheet | 按查询分页（5000条） | 单个 Excel | 数据量小、无分 Sheet 需求 || 优化 | 数据 → Sheet | 每 1000 条切分 | 单个 Excel | 需要控制单 Sheet 数据量 || 进阶 | 数据 → batchNo → Sheet | 每 1000 条切分 | 多 Excel + ZIP | 按字段分文件、单文件多 Sheet || 简化 | 数据 → batchNo | 不切分，单 Sheet | 多 Excel + ZIP | 按字段分文件、单文件单 Sheet |
选型原则：
1. 数据量小（几万条以内）：用"一个 Excel 多 Sheet"，简单直接2. 需要按字段分文件：用"多 Excel + ZIP"，每个文件独立3. 单 Sheet 数据量要控制：用"每 N 条切分"，注意合并顺序4. 数据量极大（几十万条以上）：内存方案要换成临时文件，下一篇详细讲
这一篇讲的是"单线程写 Excel"的演进，下一篇我们会进入更进阶的话题：如何用线程池并行生成多个 Excel，以及如何用流式写盘彻底解决大数据量导出的 OOM 问题。
EasyExcel 的多 Sheet 写入，本质上是"数据组织 + Sheet 索引计算"两件事。理清了数据流向，代码自然就清晰了。
实例中的easyexcel版本：2.2.11
实体类AssetIssueDetailExVo
@HeadRowHeight(25)@ContentRowHeight(20)public class AssetIssueDetailExVo {/** * 批次编号*/@ColumnWidth(17)@ExcelProperty("发放批号")private String batchNo;/** * 用户账号*/@ColumnWidth(15)@ExcelProperty("用户账号")private String account;/** * 用户名称*/@ColumnWidth(12)@ExcelProperty("用户名称")private String name;/** * 手机号*/@ColumnWidth(15)@ExcelProperty("手机号")private String phone;/** * 初始资产*/@ColumnWidth(10)@ExcelProperty("发放额度")private BigDecimal initialPoint;/** * 积分发放时间*/@ColumnWidth(20)@ExcelProperty("发放时间")private Date issuedTime;/** * 发放状态：0-未发放；1-已发放*/@ExcelIgnoreprivate Boolean issuedState;@ColumnWidth(12)@ExcelProperty("发放状态")private String issuedStateText;/** * 企业商城名称*/@ColumnWidth(20)@ExcelProperty("商城名称")private String companyName;
// get/set方法忽略}线程池AsyncTaskExecutePool
@Configuration
public class AsyncTaskExecutePool implements AsyncConfigurer {
private static final Logger log = LoggerFactory.getLogger(AsyncTaskExecutePool.class);
@Override
public Executor getAsyncExecutor() {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setTaskDecorator(runnable -> {
Map<String, String> context = MDC.getCopyOfContextMap();
return () -> {
if (context != null) {
MDC.setContextMap(context);
}
try {
runnable.run();
} finally {
MDC.clear();
}
};
});
//核心线程池大小
executor.setCorePoolSize(5);
//最大线程数
executor.setMaxPoolSize(10);
//队列容量
executor.setQueueCapacity(100);
//活跃时间
executor.setKeepAliveSeconds(60);
//线程名字前缀
executor.setThreadNamePrefix("juyou-async-");
// setRejectedExecutionHandler：当pool已经达到max size的时候，如何处理新任务
// CallerRunsPolicy：不在新线程中执行任务，而是由调用者所在的线程来执行
executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
executor.setWaitForTasksToCompleteOnShutdown(true); // 开启优雅停机
executor.setAwaitTerminationSeconds(60); // 最多等待 60 秒
executor.initialize();
return executor;
}