做后端的兄弟应该都碰到过这类需求业务方丢过来一个 Excel说“把每行数据拆成一个新的 Excel 文件再打个包给我下载”。第一次听到这需求我第一反应是用 POI 直接读、直接写但一轮做完就发现小文件还行一旦数据量过万内存直接扛不住而且 POI 写起来又臭又长。后面换了阿里开源的 EasyExcel 重新做这条链路效果才真正稳定下来读得轻、写得快、代码量也少。这篇就按照我实际落地过的方案完整聊一聊怎么用 EasyExcel 读取源 Excel 的每一行数据把每行生成一个独立的 xlsx 文件再通过 ZipOutputStream 打包成 ZIP 下载。整个过程包含代码、参数取舍、生产环境要注意的坑以及我踩过的一些问题。适合正在做报表导出、批量分发、数据拆单这类需求的 Java 后端开发者无论你用的是 Spring Boot 还是纯 Java 工程思路都通用。1. 先说清楚需求每行数据到底要拆成什么1.1 需求场景还原这类需求在实际业务里非常常见。比如运营给了一个几百行的商品清单要求按每个商品单独生成一份报价 Excel避免把全部数据直接暴露给渠道商再比如财务导出一张全量账单下游机构要求一个客户一个文件最后全部压缩成一个 ZIP 包。本质上都是源文件只有一个 Excel可能是一个 Sheet可能是多个 Sheet每一行是一条完整业务数据目标不是把整个文件转换格式而是按行粒度拆分拆分后的文件要能在压缩包里逐个下载。举个具体例子源 Excel 是这样的订单号用户名商品金额A001张三鼠标99.00A002李四键盘199.00A003王五显示器1299.00希望生成的 ZIP 里有三个 xlsxorder_1.xlsx 里只有 A001 这行带表头order_2.xlsx 里只有 A002 这行order_3.xlsx 里只有 A003 这行。这就是“每行数据转成 Excel 表格格式数据”的典型含义。1.2 技术选型为什么用 EasyExcel 而不是 POIJava 处理 Excel 绕不开 POI但我们在选型时要想清楚这个场景的核心难点不是“能不能解析”而是“怎么控制内存”。POI 的常用读写模式是把整个工作簿加载成对象树一个 10 万行的 Excel 就能吃掉几百 MB 内存如果数据量更大GC 频繁不说甚至直接把服务 OOM 掉。而且 POI 写 Excel 的底层 API 非常琐碎创建 CellStyle、创建 Row、创建 Cell代码量爆炸维护成本很高。EasyExcel 是阿里开源的一套 Excel 处理组件它最大的特点是流式读写。读取时通过事件监听机制解析不会一次性把整个文件加载到内存写入时也支持边写边刷。配合注解声明列字段代码量比 POI 少一个量级。它还内置了很多实用功能比如日期格式化、自定义样式、动态表头、模板填充这些都直接解决我们在拆分场景里的痛点。也有人会问直接用 CSV 然后打包 ZIP 不行吗CSV 在纯数据场景下确实轻量文件体积小读取也简单。但业务方要求的是“Excel 文件”CSV 在格式上天然不算。更重要的是CSV 无法保留表头样式、列宽、多 Sheet、单元格类型如果其中一列是金额CSV 转出来可能变成科学计数法或丢精度。所以只要要求的是格式完整的 xlsxEasyExcel 就是最合适的选择。2. 方案设计一条完整的拆行导出链路2.1 整体数据流我落地时的设计分五步EasyExcel 读取源 Excel通过自定义 Listener 把每一行数据回调到收集器数据收集到一个 List 中用于后续按行拆分循环遍历 List每次把一行数据交给 EasyExcel 写入一个独立的 ByteArrayOutputStream将 ByteArrayOutputStream 的字节写入 ZipOutputStream 的一个 Entry最后把 ZipOutputStream 连接到 HttpServletResponse 的输出流浏览器直接下载 ZIP。这套流程不算复杂但要注意一个顺序问题先读完再拆而不是边读边拆。原因有三点一是源文件可能有脏数据或者需要校验先读后拆便于在读完后决定“这行要不要生成文件”二是文件命名可能需要依赖行序号比如 order_1、order_2全量读取后用 index 控制最方便三是如果中间处理失败全量 List 还在内存里可以基于数据重试不用重新解析源文件。2.2 使用 Listener 还是全量加载EasyExcel 提供了两种常见的读取方式一种是直接doReadAllSync()返回 List另一种是注册AnalysisEventListener通过invoke()逐行回调。对于拆行导出我更推荐 Listener 方式。因为源 Excel 可能很大doReadAllSync()虽然内部也是流式但它最后会把所有数据汇总到一个 List 返回本质上和全量加载没有区别。而 Listener 方式让你有机会在每行数据到达时就决定是收集还是直接丢弃比如过滤空行、过滤无效行。如果你只是想把数据先全部收集起来Listener 里的invoke()就是往 List 里 add 一下代码也很简单。需要注意的坑是Listener 如果是个普通内部类通过new创建的实例无法注入 Spring 管理后面我会专门讲这个。2.3 内存与文件句柄的关键取舍每行数据生成一个 xlsx这步的核心问题不是“能不能写”而是“写到哪儿”。第一反应是把每个 Excel 文件写到磁盘生成几十个临时文件最后再一个个读进 ZIP。这样最稳妥但磁盘 IO 多还要处理临时文件清理。后来我改成每个 Excel 写到一个 ByteArrayOutputStream拿到 byte[] 后立即塞进 ZIP Entry。这样每个文件几乎不产生磁盘写入速度很快。但这个方法有上限如果一行数据的列特别多比如几十列长文本或者文件数量特别多ByteArrayOutputStream 本身就会占用大量堆内存。比如一次拆 10 万个文件每个文件平均 2KB那就是接近 200MB 的内存开销再加上源数据 List服务很容易出现 Full GC。所以真实生产环境里我会做一个阈值判断当预计生成文件数量小于 5000 且单行数据不长时用 ByteArrayOutputStream超过这个规模改用临时文件。临时文件方案在后面优化章节详细展开。3. 实战代码一个可直接落地的下载接口3.1 引入依赖我用的是 Maven 工程只加了 EasyExcel 一个核心依赖。Spring Boot 版本用的 2.7但 EasyExcel 本身和 Spring 版本没有强绑定普通 Java 工程也能跑。dependency groupIdcom.alibaba/groupId artifactIdeasyexcel/artifactId version3.3.4/version /dependencyEasyExcel 3.x 要求 JDK8 及以上。它底层依赖 POI但不需要你额外引用 POI依赖传递会自动带进来。如果你的项目里本身也有 POI注意版本冲突尤其是poi-ooxml的版本冲突时按报错提示排除即可。3.2 定义一个数据模型拆行导出之前先要把源 Excel 的列映射成 Java 对象。EasyExcel 提供了强大的注解方式强烈推荐使用。Getter Setter public class OrderRow { ExcelProperty(value 订单号) private String orderNo; ExcelProperty(value 用户名) private String username; ExcelProperty(value 商品名称) private String productName; ExcelProperty(value 下单时间) DateTimeFormat(yyyy-MM-dd HH:mm:ss) private Date createTime; ExcelProperty(value 金额) private BigDecimal amount; }ExcelProperty通过表头文字完成字段映射也可以指定index按列序号映射。这一点很重要源 Excel 表头经常会被业务方手动改几个字如果你的代码依赖表头文字一改就错位。所以我更推荐在列结构稳定的情况下加上indexExcelProperty(index 0) private String orderNo;这样读的时候只看第几列不看表头叫什么抗干扰能力强很多。3.3 读取源 Excel自定义 Listener这里定义一个监听器收集所有行数据。我不推荐在 Listener 里直接做拆文件写入 ZIP 的操作职责不清晰后期不好维护。public class OrderRowListener extends AnalysisEventListenerOrderRow { private final ListOrderRow rows new ArrayList(); Override public void invoke(OrderRow row, AnalysisContext context) { if (row null) { return; } rows.add(row); } Override public void doAfterAllAnalysed(AnalysisContext context) { // 所有行解析完成可以在这里打日志 } public ListOrderRow getRows() { return rows; } }读取源文件时用 EasyExcel 的read()方法public ListOrderRow readSourceExcel(InputStream inputStream) { OrderRowListener listener new OrderRowListener(); EasyExcel.read(inputStream, OrderRow.class, listener) .sheet() .doRead(); return listener.getRows(); }.sheet()不传参数默认读第一个 Sheet。如果源 Excel 有多个 Sheet需要每个 Sheet 都读可以循环.sheet(sheetName).doRead()但注意同一个 Excel 的 Sheet 不能重复读建议用ExcelReader配合ReadSheet对象管理。3.4 核心方法一行数据生成一个 Excel 文件这是整个需求里最核心的一步把一行数据变成一个 xlsx。我用一个独立方法封装输入是一行数据和动态表头输出是 byte[]。这样后续无论写 ZIP 还是写临时文件都复用同一个方法。private byte[] buildSingleRowExcel(ListString headRow, OrderRow row) { // 注意这里必须用 ByteArrayOutputStream不能直接把 ZipOutputStream 传给 EasyExcel try (ByteArrayOutputStream baos new ByteArrayOutputStream()) { EasyExcel.write(baos) .head(headRow) // 动态表头 .sheet(单行数据) .doWrite(Collections.singletonList(row)); return baos.toByteArray(); } catch (IOException e) { throw new RuntimeException(生成单行Excel失败, e); } }headRow 是一个 List 比如ListString headRow Arrays.asList(订单号, 用户名, 商品名称, 下单时间, 金额);使用动态表头的好处是即使你没有定义OrderRow这样的模型类也能用ListListString直接写数据适合列结构不固定的场景。如果你已经定义了 OrderRow想省事也可以用EasyExcel.write(baos, OrderRow.class)这种方式。两种写法效果一样区别在于动态表头更灵活固定模型更利于类型校验。我自己更偏向于表头列少用动态表头列多且类型复杂的用模型类加注解。3.5 打包成 ZIP 的逻辑ZIP 部分用 java.util.zip 包下的 ZipOutputStream这个属于 JDK 自带能力无需额外依赖。public void exportRowsAsZip(ListOrderRow rows, OutputStream outputStream) throws IOException { ListString head Arrays.asList(订单号, 用户名, 商品名称, 下单时间, 金额); ZipOutputStream zipOut new ZipOutputStream(outputStream); // 可选设置压缩级别xlsx 本身已压缩可以用 BEST_SPEED 提升速度 zipOut.setLevel(Deflater.BEST_SPEED); for (int i 0; i rows.size(); i) { OrderRow row rows.get(i); // 文件命名order_1.xlsx、order_2.xlsx String fileName order_ (i 1) .xlsx; byte[] xlsxBytes buildSingleRowExcel(head, row); zipOut.putNextEntry(new ZipEntry(fileName)); zipOut.write(xlsxBytes); zipOut.closeEntry(); } zipOut.finish(); zipOut.flush(); // 注意这里不关闭 zipOut因为底层 outputStream 可能是 response.getOutputStream() }这里我特意不把zipOut放到 try-with-resources 里。因为关闭ZipOutputStream会连带关闭底层的HttpServletResponse输出流虽然 Spring 环境下多数情况下影响不大但如果你后面还有日志输出或者需要再次往 response 里写内容就会报流已关闭。正确做法是业务代码结束后由容器统一处理底层流。如果你的场景是生成一个文件保存到服务器 / 本地磁盘那用 try-with-resources 让 zipOut 自动关闭是完全没问题的。我这个方法把“是否关闭底层流”的决策权交给调用方更灵活。3.6 Controller 层下载接口下载接口需要设置两个响应头Content-Type 和 Content-Disposition。GetMapping(/export/zip) public void exportZip(HttpServletResponse response) throws IOException { // 正常这个 List 是从源 Excel 读取得到的 ListOrderRow rows readSourceExcel(inputStream); response.setContentType(application/zip); response.setCharacterEncoding(UTF-8); String fileName URLEncoder.encode(订单拆分.zip, UTF-8) .replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment; filename\ fileName \; filename*UTF-8 fileName); exportRowsAsZip(rows, response.getOutputStream()); }URLEncoder.encode会把空格变成加号“”Http 头里是不认识加号作为空格的所以这里用.replaceAll(\\, %20)修复一下。filename是给老版本 IE 用的filename*是给现代浏览器用的两个都写上兼容性最好。3.7 完整链路代码把读取和导出串起来就是一个完整的接口PostMapping(/importAndExportZip) public void importAndExportZip(RequestParam(file) MultipartFile file, HttpServletResponse response) throws IOException { ListOrderRow rows; try (InputStream inputStream file.getInputStream()) { rows readSourceExcel(inputStream); } response.setContentType(application/zip); String fileName URLEncoder.encode(订单拆分.zip, UTF-8) .replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment; filename\ fileName \; filename*UTF-8 fileName); exportRowsAsZip(rows, response.getOutputStream()); }这个接口接收一个上传的 Excel然后立即把拆分后的 ZIP 返回给前端。实际项目中如果源文件已经存在服务器上直接传文件路径给 read 方法即可EasyExcel.read(File file, Class, Listener)这种重载是支持的。4. 生产环境必须做的优化与扩展4.1 控制内存ByteArrayOutputStream 的适用边界前面提到直接生成 byte[] 最方便但内存不是无限的。假设一行数据平均 2KB拆 5 万行生成 5 万个 byte[] 同时存在内存里就是 100MB再加上源数据 List、临时变量、响应缓冲区整个接口的瞬时内存可能突破 200MB。我建议给 buildSingleRowExcel 增加一个开关数量小走内存数量大走临时文件。临界值根据服务器堆内存和 JVM 参数设置我的经验是 1GB 堆内存的容器临界值设在 5000 行比较安全。超过后流程变成每行数据写到一个临时 xlsx 文件把临时文件写入 ZipOutputStream删除临时文件。临时文件代码示例如下File tempFile File.createTempFile(row_, .xlsx); try (FileOutputStream fos new FileOutputStream(tempFile)) { EasyExcel.write(fos) .head(head) .sheet(data) .doWrite(Collections.singletonList(row)); } try (FileInputStream fis new FileInputStream(tempFile)) { zipOut.putNextEntry(new ZipEntry(fileName)); byte[] buffer new byte[8192]; int len; while ((len fis.read(buffer)) ! -1) { zipOut.write(buffer, 0, len); } zipOut.closeEntry(); } finally { tempFile.delete(); }这里的开销主要在磁盘 IO但内存非常稳。文件名如果存在同时写多个临时文件的情况记得保证文件名唯一File.createTempFile会生成随机后缀天然避免冲突。4.2 并行拆分多个线程生成 Excel如果文件数量很大单线程循环里每次生成 Excel 再写 ZIP瓶颈在 CPU 和内存。实际优化可以把“生成 Excel byte[]”这一步并行化。一个比较省事的做法是用并行流Listbyte[] bytesList rows.parallelStream() .map(row - buildSingleRowExcel(head, row)) .collect(Collectors.toList());并行流默认使用 ForkJoinPool 公共线程池会和其他并行任务竞争不建议在 Servlet 容器里大规模使用。更好的做法是自定义线程池提交任务后按 Future 顺序取结果ExecutorService executor Executors.newFixedThreadPool(8); ListFuturebyte[] futures rows.stream() .map(row - executor.submit(() - buildSingleRowExcel(head, row))) .collect(Collectors.toList()); for (Futurebyte[] future : futures) { byte[] bytes future.get(); // 按顺序写入 zip }如果你希望 ZIP 内文件顺序和源 Excel 一致用 Future 列表按序 get 即可。如果不在乎顺序直接把 zip 写入也并行化更复杂因为 ZipOutputStream 不是线程安全的不建议多个线程同时写同一个 stream。4.3 动态分组按业务字段拆成多个文件“每行一个文件”只是最极端的情况更多时候业务方说“一个渠道一个文件”或者“一天一个文件”。这时就不能每行单独 build而是在读取时按字段分组。比如按“店铺编号”分组MapString, ListOrderRow groupMap rows.stream() .collect(Collectors.groupingBy(OrderRow::getShopId));然后每个分组生成一个 Excelfor (Map.EntryString, ListOrderRow entry : groupMap.entrySet()) { String shopId entry.getKey(); ListOrderRow groupRows entry.getValue(); String fileName shop_ shopId .xlsx; byte[] bytes buildGroupExcel(groupRows); zipOut.putNextEntry(new ZipEntry(fileName)); zipOut.write(bytes); zipOut.closeEntry(); }buildGroupExcel 和 buildSingleRowExcel 的唯一差别就是 doWrite 时传入整个 ListEasyExcel 会把它写成多行。这个扩展很实用因为一行一个文件的场景虽然存在但往往伴随着“文件数量太多导致下载时间很久、解压后文件管理困难”的问题按业务维度合并是更合理的产品方案。4.4 给拆分文件加样式和高级表头如果生成的文件还要发给外部人员看只有纯数据不够可能要在每个文件里加标题行、合并单元格、设列宽。EasyExcel 对样式有两种常见的支持方式。第一种是注解HeadRowHeight(30) HeadStyle(fillForegroundColor 23, fillPatternType FillPatternTypeEnum.SOLID_FOREGROUND) public class OrderRow { ... }fillForegroundColor 23是浅蓝色颜色索引对应 POI 的调色板不是 RGB 值这一点容易踩坑。如果你的团队对颜色有准确要求建议用自定义 WriteCellStyle 配合 RGB 颜色。第二种是代码注册 WriteHandlerEasyExcel.write(baos) .head(head) .registerWriteHandler(new LongestMatchColumnWidthStyleHandler()) .sheet(数据) .doWrite(Collections.singletonList(row));LongestMatchColumnWidthStyleHandler会根据单元格内容自动调整列宽对导出给外部看的文件很实用。注意 EasyExcel 已经内置了这款 Handler不需要自己写。5. 常见问题与排查技巧实录5.1 中文文件名乱码下载时浏览器把 ZIP 文件名显示成一串乱码原因基本都在 Content-Disposition 头。只设置filename时非 ASCII 字符在 HTTP 头里默认按 Latin-1 解析必然乱码。我最终使用的标准写法是同时设置 filename 和 filename*并且对中文做了 UTF-8 编码String fileName URLEncoder.encode(订单拆分.zip, UTF-8).replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment; filename\ fileName \; filename*UTF-8 fileName);这样 Chrome、Edge、Firefox 都能正确处理。另外ZIP 包内部的文件名不建议包含中文因为不同系统的 ZIP 解压工具对 UTF-8 中文名的支持不一致有些老版本解压会乱码。内部文件名我一般都用order_1.xlsx这种英文字母加数字。5.2 下载后的 ZIP 提示“文件已损坏”这个问题十有八九是 ZipEntry 没正确关闭或者把 ZipOutputStream 关闭时机搞错了。举一个反面案例// 错误写法 for (int i 0; i rows.size(); i) { zipOut.putNextEntry(new ZipEntry(order_ i .xlsx)); byte[] bytes buildSingleRowExcel(head, rows.get(i)); zipOut.write(bytes); // 少了 zipOut.closeEntry(); } zipOut.close();少了closeEntry()会造成 ZIP 文件的 Central Directory 数据不完整解压工具要么报损坏要么文件大小为 0。每次写完一个 Entry 一定记得关闭这是我写 ZIP 时第一个检查项。还有一种情况buildSingleRowExcel里 EasyExcel 写入 ByteArrayOutputStream 后流没有正确 flush。我上面的代码用了 try-with-resources会自动 close但如果有人只调用baos.toByteArray()而不关闭底层流大部分场景没问题但在某些 EasyExcel 版本里会出现尾部数据没刷入的情况。稳妥做法是在toByteArray()前调用baos.flush()。5.3 Listener 里注入不了 Spring Bean这个问题很典型。如果你在自定义 Listener 里写Autowired引用 Service然后在 Controller 里写new OrderRowListener()那这个 Listener 根本不受 Spring 管理自动注入必然是 null。解决办法有两种第一种构造器传参public class OrderRowListener extends AnalysisEventListenerOrderRow { private final OrderService orderService; public OrderRowListener(OrderService orderService) { this.orderService orderService; } Override public void invoke(OrderRow row, AnalysisContext context) { // 这里就能用 orderService 了 } }第二种把 Listener 注册成 Spring prototype Bean用 BeanUtils / ApplicationContext 获取Component Scope(prototype) public class OrderRowListener extends AnalysisEventListenerOrderRow { Autowired private OrderService orderService; ... } // 使用 OrderRowListener listener applicationContext.getBean(OrderRowListener.class); EasyExcel.read(inputStream, OrderRow.class, listener);我个人更推荐构造器传参简单直接不依赖 Spring 容器。5.4 写入 Excel 时提示 “Excel sub-sheet name cannot be empty”EasyExcel 写入时每个 Sheet 必须有名字。如果直接调.sheet()不传参数默认 Sheet 名是 null某些版本会报错。建议总是显式传一个名字.sheet(data)还有一点同一个 ExcelWriter 里不能创建两个同名 Sheet如果需要多个 Sheet用不同的 sheet 名称。5.5 读取 Excel 时列错位 / 数据变成科学计数法这类问题基本都是数据类型映射引起的。比如订单号是 19 位数字Excel 单元格里可能是文本但你用 Integer 接收解析就会出问题。金额字段如果源表是文本格式用 BigDecimal 接收也可能抛转换异常。我的经验是无法确定源表格式时尽量统一用 String 接收再在业务里转换。比如ExcelProperty(index 0) private String orderNo; ExcelProperty(index 4) private String amount;读取后解析时再new BigDecimal(row.getAmount())。这样做虽然损失了一点自动类型转换的便利但稳定性高很多真正的生产环境里源 Excel 的脏数据远比想象的多样。5.6 ZIP 文件体积异常大每个 xlsx 本身已经是 ZIP 压缩格式再把它们二次压进外层 ZIP压缩率几乎为零所以外层 ZIP 的大小差不多等于所有 xlsx 大小之和。这没问题。但如果你发现 ZIP 体积比所有 xlsx 加起来还大很多多半是因为压缩级别设置不合理或者每个 Entry 写入低效。ZipOutputStream.setLevel(Deflater.BEST_SPEED)可以减少冗余计算配合 8KB buffer 写入性能会改善。如果你是直接把 byte[] 一次性 write本身效率已经不低瓶颈一般在生成 byte[] 的 CPU 消耗上。还有一个可能ByteArrayOutputStream 初始化容量太小不断扩容导致拷贝开销。如果单行数据量特别大可以预设容量ByteArrayOutputStream baos new ByteArrayOutputStream(4096);缺点是需要预估大小估小了没用估大了浪费。一般单行十列以内4KB 足够。最后分享一点我的经验拆行导出这个需求技术上不算难但真正做到生产级稳定靠的不是某一个 API 用得熟而是对内存流向的理解。每一行数据是留在内存、写临时文件还是直接进 ZIP决定了整个接口能扛住多大的数据量。我做第一版时就很天真地全部放内存结果 8 万行数据直接把测试环境搞到频繁 Full GC后来改成临时文件加分组导出问题才彻底解决。建议大家在接需求时先确认两件事预计多少行数据、是否真的需要一行一个文件。大多数时候按业务字段分组合并成几十个文件才是业务方真正想要的方案而不是机械地拆成几千个小文件让下游也头疼。
做后端的兄弟应该都碰到过这类需求业务方丢过来一个 Excel说“把每行数据拆成一个新的 Excel 文件再打个包给我下载”。第一次听到这需求我第一反应是用 POI 直接读、直接写但一轮做完就发现小文件还行一旦数据量过万内存直接扛不住而且 POI 写起来又臭又长。后面换了阿里开源的 EasyExcel 重新做这条链路效果才真正稳定下来读得轻、写得快、代码量也少。这篇就按照我实际落地过的方案完整聊一聊怎么用 EasyExcel 读取源 Excel 的每一行数据把每行生成一个独立的 xlsx 文件再通过 ZipOutputStream 打包成 ZIP 下载。整个过程包含代码、参数取舍、生产环境要注意的坑以及我踩过的一些问题。适合正在做报表导出、批量分发、数据拆单这类需求的 Java 后端开发者无论你用的是 Spring Boot 还是纯 Java 工程思路都通用。1. 先说清楚需求每行数据到底要拆成什么1.1 需求场景还原这类需求在实际业务里非常常见。比如运营给了一个几百行的商品清单要求按每个商品单独生成一份报价 Excel避免把全部数据直接暴露给渠道商再比如财务导出一张全量账单下游机构要求一个客户一个文件最后全部压缩成一个 ZIP 包。本质上都是源文件只有一个 Excel可能是一个 Sheet可能是多个 Sheet每一行是一条完整业务数据目标不是把整个文件转换格式而是按行粒度拆分拆分后的文件要能在压缩包里逐个下载。举个具体例子源 Excel 是这样的订单号用户名商品金额A001张三鼠标99.00A002李四键盘199.00A003王五显示器1299.00希望生成的 ZIP 里有三个 xlsxorder_1.xlsx 里只有 A001 这行带表头order_2.xlsx 里只有 A002 这行order_3.xlsx 里只有 A003 这行。这就是“每行数据转成 Excel 表格格式数据”的典型含义。1.2 技术选型为什么用 EasyExcel 而不是 POIJava 处理 Excel 绕不开 POI但我们在选型时要想清楚这个场景的核心难点不是“能不能解析”而是“怎么控制内存”。POI 的常用读写模式是把整个工作簿加载成对象树一个 10 万行的 Excel 就能吃掉几百 MB 内存如果数据量更大GC 频繁不说甚至直接把服务 OOM 掉。而且 POI 写 Excel 的底层 API 非常琐碎创建 CellStyle、创建 Row、创建 Cell代码量爆炸维护成本很高。EasyExcel 是阿里开源的一套 Excel 处理组件它最大的特点是流式读写。读取时通过事件监听机制解析不会一次性把整个文件加载到内存写入时也支持边写边刷。配合注解声明列字段代码量比 POI 少一个量级。它还内置了很多实用功能比如日期格式化、自定义样式、动态表头、模板填充这些都直接解决我们在拆分场景里的痛点。也有人会问直接用 CSV 然后打包 ZIP 不行吗CSV 在纯数据场景下确实轻量文件体积小读取也简单。但业务方要求的是“Excel 文件”CSV 在格式上天然不算。更重要的是CSV 无法保留表头样式、列宽、多 Sheet、单元格类型如果其中一列是金额CSV 转出来可能变成科学计数法或丢精度。所以只要要求的是格式完整的 xlsxEasyExcel 就是最合适的选择。2. 方案设计一条完整的拆行导出链路2.1 整体数据流我落地时的设计分五步EasyExcel 读取源 Excel通过自定义 Listener 把每一行数据回调到收集器数据收集到一个 List 中用于后续按行拆分循环遍历 List每次把一行数据交给 EasyExcel 写入一个独立的 ByteArrayOutputStream将 ByteArrayOutputStream 的字节写入 ZipOutputStream 的一个 Entry最后把 ZipOutputStream 连接到 HttpServletResponse 的输出流浏览器直接下载 ZIP。这套流程不算复杂但要注意一个顺序问题先读完再拆而不是边读边拆。原因有三点一是源文件可能有脏数据或者需要校验先读后拆便于在读完后决定“这行要不要生成文件”二是文件命名可能需要依赖行序号比如 order_1、order_2全量读取后用 index 控制最方便三是如果中间处理失败全量 List 还在内存里可以基于数据重试不用重新解析源文件。2.2 使用 Listener 还是全量加载EasyExcel 提供了两种常见的读取方式一种是直接doReadAllSync()返回 List另一种是注册AnalysisEventListener通过invoke()逐行回调。对于拆行导出我更推荐 Listener 方式。因为源 Excel 可能很大doReadAllSync()虽然内部也是流式但它最后会把所有数据汇总到一个 List 返回本质上和全量加载没有区别。而 Listener 方式让你有机会在每行数据到达时就决定是收集还是直接丢弃比如过滤空行、过滤无效行。如果你只是想把数据先全部收集起来Listener 里的invoke()就是往 List 里 add 一下代码也很简单。需要注意的坑是Listener 如果是个普通内部类通过new创建的实例无法注入 Spring 管理后面我会专门讲这个。2.3 内存与文件句柄的关键取舍每行数据生成一个 xlsx这步的核心问题不是“能不能写”而是“写到哪儿”。第一反应是把每个 Excel 文件写到磁盘生成几十个临时文件最后再一个个读进 ZIP。这样最稳妥但磁盘 IO 多还要处理临时文件清理。后来我改成每个 Excel 写到一个 ByteArrayOutputStream拿到 byte[] 后立即塞进 ZIP Entry。这样每个文件几乎不产生磁盘写入速度很快。但这个方法有上限如果一行数据的列特别多比如几十列长文本或者文件数量特别多ByteArrayOutputStream 本身就会占用大量堆内存。比如一次拆 10 万个文件每个文件平均 2KB那就是接近 200MB 的内存开销再加上源数据 List服务很容易出现 Full GC。所以真实生产环境里我会做一个阈值判断当预计生成文件数量小于 5000 且单行数据不长时用 ByteArrayOutputStream超过这个规模改用临时文件。临时文件方案在后面优化章节详细展开。3. 实战代码一个可直接落地的下载接口3.1 引入依赖我用的是 Maven 工程只加了 EasyExcel 一个核心依赖。Spring Boot 版本用的 2.7但 EasyExcel 本身和 Spring 版本没有强绑定普通 Java 工程也能跑。dependency groupIdcom.alibaba/groupId artifactIdeasyexcel/artifactId version3.3.4/version /dependencyEasyExcel 3.x 要求 JDK8 及以上。它底层依赖 POI但不需要你额外引用 POI依赖传递会自动带进来。如果你的项目里本身也有 POI注意版本冲突尤其是poi-ooxml的版本冲突时按报错提示排除即可。3.2 定义一个数据模型拆行导出之前先要把源 Excel 的列映射成 Java 对象。EasyExcel 提供了强大的注解方式强烈推荐使用。Getter Setter public class OrderRow { ExcelProperty(value 订单号) private String orderNo; ExcelProperty(value 用户名) private String username; ExcelProperty(value 商品名称) private String productName; ExcelProperty(value 下单时间) DateTimeFormat(yyyy-MM-dd HH:mm:ss) private Date createTime; ExcelProperty(value 金额) private BigDecimal amount; }ExcelProperty通过表头文字完成字段映射也可以指定index按列序号映射。这一点很重要源 Excel 表头经常会被业务方手动改几个字如果你的代码依赖表头文字一改就错位。所以我更推荐在列结构稳定的情况下加上indexExcelProperty(index 0) private String orderNo;这样读的时候只看第几列不看表头叫什么抗干扰能力强很多。3.3 读取源 Excel自定义 Listener这里定义一个监听器收集所有行数据。我不推荐在 Listener 里直接做拆文件写入 ZIP 的操作职责不清晰后期不好维护。public class OrderRowListener extends AnalysisEventListenerOrderRow { private final ListOrderRow rows new ArrayList(); Override public void invoke(OrderRow row, AnalysisContext context) { if (row null) { return; } rows.add(row); } Override public void doAfterAllAnalysed(AnalysisContext context) { // 所有行解析完成可以在这里打日志 } public ListOrderRow getRows() { return rows; } }读取源文件时用 EasyExcel 的read()方法public ListOrderRow readSourceExcel(InputStream inputStream) { OrderRowListener listener new OrderRowListener(); EasyExcel.read(inputStream, OrderRow.class, listener) .sheet() .doRead(); return listener.getRows(); }.sheet()不传参数默认读第一个 Sheet。如果源 Excel 有多个 Sheet需要每个 Sheet 都读可以循环.sheet(sheetName).doRead()但注意同一个 Excel 的 Sheet 不能重复读建议用ExcelReader配合ReadSheet对象管理。3.4 核心方法一行数据生成一个 Excel 文件这是整个需求里最核心的一步把一行数据变成一个 xlsx。我用一个独立方法封装输入是一行数据和动态表头输出是 byte[]。这样后续无论写 ZIP 还是写临时文件都复用同一个方法。private byte[] buildSingleRowExcel(ListString headRow, OrderRow row) { // 注意这里必须用 ByteArrayOutputStream不能直接把 ZipOutputStream 传给 EasyExcel try (ByteArrayOutputStream baos new ByteArrayOutputStream()) { EasyExcel.write(baos) .head(headRow) // 动态表头 .sheet(单行数据) .doWrite(Collections.singletonList(row)); return baos.toByteArray(); } catch (IOException e) { throw new RuntimeException(生成单行Excel失败, e); } }headRow 是一个 List 比如ListString headRow Arrays.asList(订单号, 用户名, 商品名称, 下单时间, 金额);使用动态表头的好处是即使你没有定义OrderRow这样的模型类也能用ListListString直接写数据适合列结构不固定的场景。如果你已经定义了 OrderRow想省事也可以用EasyExcel.write(baos, OrderRow.class)这种方式。两种写法效果一样区别在于动态表头更灵活固定模型更利于类型校验。我自己更偏向于表头列少用动态表头列多且类型复杂的用模型类加注解。3.5 打包成 ZIP 的逻辑ZIP 部分用 java.util.zip 包下的 ZipOutputStream这个属于 JDK 自带能力无需额外依赖。public void exportRowsAsZip(ListOrderRow rows, OutputStream outputStream) throws IOException { ListString head Arrays.asList(订单号, 用户名, 商品名称, 下单时间, 金额); ZipOutputStream zipOut new ZipOutputStream(outputStream); // 可选设置压缩级别xlsx 本身已压缩可以用 BEST_SPEED 提升速度 zipOut.setLevel(Deflater.BEST_SPEED); for (int i 0; i rows.size(); i) { OrderRow row rows.get(i); // 文件命名order_1.xlsx、order_2.xlsx String fileName order_ (i 1) .xlsx; byte[] xlsxBytes buildSingleRowExcel(head, row); zipOut.putNextEntry(new ZipEntry(fileName)); zipOut.write(xlsxBytes); zipOut.closeEntry(); } zipOut.finish(); zipOut.flush(); // 注意这里不关闭 zipOut因为底层 outputStream 可能是 response.getOutputStream() }这里我特意不把zipOut放到 try-with-resources 里。因为关闭ZipOutputStream会连带关闭底层的HttpServletResponse输出流虽然 Spring 环境下多数情况下影响不大但如果你后面还有日志输出或者需要再次往 response 里写内容就会报流已关闭。正确做法是业务代码结束后由容器统一处理底层流。如果你的场景是生成一个文件保存到服务器 / 本地磁盘那用 try-with-resources 让 zipOut 自动关闭是完全没问题的。我这个方法把“是否关闭底层流”的决策权交给调用方更灵活。3.6 Controller 层下载接口下载接口需要设置两个响应头Content-Type 和 Content-Disposition。GetMapping(/export/zip) public void exportZip(HttpServletResponse response) throws IOException { // 正常这个 List 是从源 Excel 读取得到的 ListOrderRow rows readSourceExcel(inputStream); response.setContentType(application/zip); response.setCharacterEncoding(UTF-8); String fileName URLEncoder.encode(订单拆分.zip, UTF-8) .replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment; filename\ fileName \; filename*UTF-8 fileName); exportRowsAsZip(rows, response.getOutputStream()); }URLEncoder.encode会把空格变成加号“”Http 头里是不认识加号作为空格的所以这里用.replaceAll(\\, %20)修复一下。filename是给老版本 IE 用的filename*是给现代浏览器用的两个都写上兼容性最好。3.7 完整链路代码把读取和导出串起来就是一个完整的接口PostMapping(/importAndExportZip) public void importAndExportZip(RequestParam(file) MultipartFile file, HttpServletResponse response) throws IOException { ListOrderRow rows; try (InputStream inputStream file.getInputStream()) { rows readSourceExcel(inputStream); } response.setContentType(application/zip); String fileName URLEncoder.encode(订单拆分.zip, UTF-8) .replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment; filename\ fileName \; filename*UTF-8 fileName); exportRowsAsZip(rows, response.getOutputStream()); }这个接口接收一个上传的 Excel然后立即把拆分后的 ZIP 返回给前端。实际项目中如果源文件已经存在服务器上直接传文件路径给 read 方法即可EasyExcel.read(File file, Class, Listener)这种重载是支持的。4. 生产环境必须做的优化与扩展4.1 控制内存ByteArrayOutputStream 的适用边界前面提到直接生成 byte[] 最方便但内存不是无限的。假设一行数据平均 2KB拆 5 万行生成 5 万个 byte[] 同时存在内存里就是 100MB再加上源数据 List、临时变量、响应缓冲区整个接口的瞬时内存可能突破 200MB。我建议给 buildSingleRowExcel 增加一个开关数量小走内存数量大走临时文件。临界值根据服务器堆内存和 JVM 参数设置我的经验是 1GB 堆内存的容器临界值设在 5000 行比较安全。超过后流程变成每行数据写到一个临时 xlsx 文件把临时文件写入 ZipOutputStream删除临时文件。临时文件代码示例如下File tempFile File.createTempFile(row_, .xlsx); try (FileOutputStream fos new FileOutputStream(tempFile)) { EasyExcel.write(fos) .head(head) .sheet(data) .doWrite(Collections.singletonList(row)); } try (FileInputStream fis new FileInputStream(tempFile)) { zipOut.putNextEntry(new ZipEntry(fileName)); byte[] buffer new byte[8192]; int len; while ((len fis.read(buffer)) ! -1) { zipOut.write(buffer, 0, len); } zipOut.closeEntry(); } finally { tempFile.delete(); }这里的开销主要在磁盘 IO但内存非常稳。文件名如果存在同时写多个临时文件的情况记得保证文件名唯一File.createTempFile会生成随机后缀天然避免冲突。4.2 并行拆分多个线程生成 Excel如果文件数量很大单线程循环里每次生成 Excel 再写 ZIP瓶颈在 CPU 和内存。实际优化可以把“生成 Excel byte[]”这一步并行化。一个比较省事的做法是用并行流Listbyte[] bytesList rows.parallelStream() .map(row - buildSingleRowExcel(head, row)) .collect(Collectors.toList());并行流默认使用 ForkJoinPool 公共线程池会和其他并行任务竞争不建议在 Servlet 容器里大规模使用。更好的做法是自定义线程池提交任务后按 Future 顺序取结果ExecutorService executor Executors.newFixedThreadPool(8); ListFuturebyte[] futures rows.stream() .map(row - executor.submit(() - buildSingleRowExcel(head, row))) .collect(Collectors.toList()); for (Futurebyte[] future : futures) { byte[] bytes future.get(); // 按顺序写入 zip }如果你希望 ZIP 内文件顺序和源 Excel 一致用 Future 列表按序 get 即可。如果不在乎顺序直接把 zip 写入也并行化更复杂因为 ZipOutputStream 不是线程安全的不建议多个线程同时写同一个 stream。4.3 动态分组按业务字段拆成多个文件“每行一个文件”只是最极端的情况更多时候业务方说“一个渠道一个文件”或者“一天一个文件”。这时就不能每行单独 build而是在读取时按字段分组。比如按“店铺编号”分组MapString, ListOrderRow groupMap rows.stream() .collect(Collectors.groupingBy(OrderRow::getShopId));然后每个分组生成一个 Excelfor (Map.EntryString, ListOrderRow entry : groupMap.entrySet()) { String shopId entry.getKey(); ListOrderRow groupRows entry.getValue(); String fileName shop_ shopId .xlsx; byte[] bytes buildGroupExcel(groupRows); zipOut.putNextEntry(new ZipEntry(fileName)); zipOut.write(bytes); zipOut.closeEntry(); }buildGroupExcel 和 buildSingleRowExcel 的唯一差别就是 doWrite 时传入整个 ListEasyExcel 会把它写成多行。这个扩展很实用因为一行一个文件的场景虽然存在但往往伴随着“文件数量太多导致下载时间很久、解压后文件管理困难”的问题按业务维度合并是更合理的产品方案。4.4 给拆分文件加样式和高级表头如果生成的文件还要发给外部人员看只有纯数据不够可能要在每个文件里加标题行、合并单元格、设列宽。EasyExcel 对样式有两种常见的支持方式。第一种是注解HeadRowHeight(30) HeadStyle(fillForegroundColor 23, fillPatternType FillPatternTypeEnum.SOLID_FOREGROUND) public class OrderRow { ... }fillForegroundColor 23是浅蓝色颜色索引对应 POI 的调色板不是 RGB 值这一点容易踩坑。如果你的团队对颜色有准确要求建议用自定义 WriteCellStyle 配合 RGB 颜色。第二种是代码注册 WriteHandlerEasyExcel.write(baos) .head(head) .registerWriteHandler(new LongestMatchColumnWidthStyleHandler()) .sheet(数据) .doWrite(Collections.singletonList(row));LongestMatchColumnWidthStyleHandler会根据单元格内容自动调整列宽对导出给外部看的文件很实用。注意 EasyExcel 已经内置了这款 Handler不需要自己写。5. 常见问题与排查技巧实录5.1 中文文件名乱码下载时浏览器把 ZIP 文件名显示成一串乱码原因基本都在 Content-Disposition 头。只设置filename时非 ASCII 字符在 HTTP 头里默认按 Latin-1 解析必然乱码。我最终使用的标准写法是同时设置 filename 和 filename*并且对中文做了 UTF-8 编码String fileName URLEncoder.encode(订单拆分.zip, UTF-8).replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment; filename\ fileName \; filename*UTF-8 fileName);这样 Chrome、Edge、Firefox 都能正确处理。另外ZIP 包内部的文件名不建议包含中文因为不同系统的 ZIP 解压工具对 UTF-8 中文名的支持不一致有些老版本解压会乱码。内部文件名我一般都用order_1.xlsx这种英文字母加数字。5.2 下载后的 ZIP 提示“文件已损坏”这个问题十有八九是 ZipEntry 没正确关闭或者把 ZipOutputStream 关闭时机搞错了。举一个反面案例// 错误写法 for (int i 0; i rows.size(); i) { zipOut.putNextEntry(new ZipEntry(order_ i .xlsx)); byte[] bytes buildSingleRowExcel(head, rows.get(i)); zipOut.write(bytes); // 少了 zipOut.closeEntry(); } zipOut.close();少了closeEntry()会造成 ZIP 文件的 Central Directory 数据不完整解压工具要么报损坏要么文件大小为 0。每次写完一个 Entry 一定记得关闭这是我写 ZIP 时第一个检查项。还有一种情况buildSingleRowExcel里 EasyExcel 写入 ByteArrayOutputStream 后流没有正确 flush。我上面的代码用了 try-with-resources会自动 close但如果有人只调用baos.toByteArray()而不关闭底层流大部分场景没问题但在某些 EasyExcel 版本里会出现尾部数据没刷入的情况。稳妥做法是在toByteArray()前调用baos.flush()。5.3 Listener 里注入不了 Spring Bean这个问题很典型。如果你在自定义 Listener 里写Autowired引用 Service然后在 Controller 里写new OrderRowListener()那这个 Listener 根本不受 Spring 管理自动注入必然是 null。解决办法有两种第一种构造器传参public class OrderRowListener extends AnalysisEventListenerOrderRow { private final OrderService orderService; public OrderRowListener(OrderService orderService) { this.orderService orderService; } Override public void invoke(OrderRow row, AnalysisContext context) { // 这里就能用 orderService 了 } }第二种把 Listener 注册成 Spring prototype Bean用 BeanUtils / ApplicationContext 获取Component Scope(prototype) public class OrderRowListener extends AnalysisEventListenerOrderRow { Autowired private OrderService orderService; ... } // 使用 OrderRowListener listener applicationContext.getBean(OrderRowListener.class); EasyExcel.read(inputStream, OrderRow.class, listener);我个人更推荐构造器传参简单直接不依赖 Spring 容器。5.4 写入 Excel 时提示 “Excel sub-sheet name cannot be empty”EasyExcel 写入时每个 Sheet 必须有名字。如果直接调.sheet()不传参数默认 Sheet 名是 null某些版本会报错。建议总是显式传一个名字.sheet(data)还有一点同一个 ExcelWriter 里不能创建两个同名 Sheet如果需要多个 Sheet用不同的 sheet 名称。5.5 读取 Excel 时列错位 / 数据变成科学计数法这类问题基本都是数据类型映射引起的。比如订单号是 19 位数字Excel 单元格里可能是文本但你用 Integer 接收解析就会出问题。金额字段如果源表是文本格式用 BigDecimal 接收也可能抛转换异常。我的经验是无法确定源表格式时尽量统一用 String 接收再在业务里转换。比如ExcelProperty(index 0) private String orderNo; ExcelProperty(index 4) private String amount;读取后解析时再new BigDecimal(row.getAmount())。这样做虽然损失了一点自动类型转换的便利但稳定性高很多真正的生产环境里源 Excel 的脏数据远比想象的多样。5.6 ZIP 文件体积异常大每个 xlsx 本身已经是 ZIP 压缩格式再把它们二次压进外层 ZIP压缩率几乎为零所以外层 ZIP 的大小差不多等于所有 xlsx 大小之和。这没问题。但如果你发现 ZIP 体积比所有 xlsx 加起来还大很多多半是因为压缩级别设置不合理或者每个 Entry 写入低效。ZipOutputStream.setLevel(Deflater.BEST_SPEED)可以减少冗余计算配合 8KB buffer 写入性能会改善。如果你是直接把 byte[] 一次性 write本身效率已经不低瓶颈一般在生成 byte[] 的 CPU 消耗上。还有一个可能ByteArrayOutputStream 初始化容量太小不断扩容导致拷贝开销。如果单行数据量特别大可以预设容量ByteArrayOutputStream baos new ByteArrayOutputStream(4096);缺点是需要预估大小估小了没用估大了浪费。一般单行十列以内4KB 足够。最后分享一点我的经验拆行导出这个需求技术上不算难但真正做到生产级稳定靠的不是某一个 API 用得熟而是对内存流向的理解。每一行数据是留在内存、写临时文件还是直接进 ZIP决定了整个接口能扛住多大的数据量。我做第一版时就很天真地全部放内存结果 8 万行数据直接把测试环境搞到频繁 Full GC后来改成临时文件加分组导出问题才彻底解决。建议大家在接需求时先确认两件事预计多少行数据、是否真的需要一行一个文件。大多数时候按业务字段分组合并成几十个文件才是业务方真正想要的方案而不是机械地拆成几千个小文件让下游也头疼。
