EasyExcel实战：从POI迁移到内存友好的导入导出方案

做过后台管理系统的 Java 开发Excel 导入导出这事十有八九躲不掉。早几年我用 Apache POI 硬啃一个 10 万行的导出就能把 JVM 堆内存顶到告警导入再碰上合并单元格、多行表头解析代码能写到怀疑人生。后来项目里全面换了 EasyExcel这批“老生常谈”的需求才算真正沉淀成了一套可复用的方案。EasyExcel 是阿里开源的一款基于 SAX 模式的 Excel 处理框架核心卖点就四个字省内存。它在解析和写入时采用流式操作不走 DOM 全量加载所以 10 万行数据导出的内存峰值可能只有 POI 的十分之一。本文不聊官方文档里已经有的大白话而是把我自己在导入导出这条路上趟过的坑、总结出的套路包括复杂表头读取、样式控制、下拉校验、工作表保护、大数据量分批写入这些高频场景一次讲清楚。适合正在用 EasyExcel 或者准备从 POI 迁移过来的后端开发同学。1. 为什么选 EasyExcelPOI 太重自研太傻1.1 EasyExcel 到底解决了什么问题先说结论POI 不是不能用而是大部分项目用错了姿势。POI 的 XSSFWorkbook 在读取时会把整个 Excel 解析成一个内存中的树形结构每个单元格、样式、合并区域都占据对象一个 5 万行的文件轻松吃掉几百 MB 堆内存。而 EasyExcel 底层用的是 SAX 事件模型逐行触发解析事件读一行处理一行写一行刷一行内存占用自然就降下来了。我做过一次很直观的对比测试同样导出一份 10 万行、20 列的报表POI 的 XSSFWorkbook 方式下 JVM 堆内存飙到 800MB 以上还伴随频繁 Full GC换成 EasyExcel 后峰值内存稳定在 50MB 左右耗时也几乎只有 POI 的一半。这个差距在线上环境就是“能不能撑过月底报表高峰”的区别。1.2 和其他方案比一比表格对比更直观方案内存占用上手成本复杂表头样式控制社区活跃度Apache POIXSSF高较高支持但代码量大强底层直接操作高Apache POISXSSF中较高支持但代码量大弱依赖低层 API高Hutool Excel中低一般一般中FastExcel低低支持支持中EasyExcel低低支持支持高EasyExcel 最舒服的一点是注解驱动。你只要在实体类上标好ExcelProperty、ColumnWidth、DateTimeFormat读写逻辑基本就完成了一大半。POI 当然也能做但同样的效果POI 的代码量至少是 EasyExcel 的三倍而且每个字段都要手动 getRow、getCell、getValue枯燥且容易下标越界。还有一点必须提醒EasyExcel 依赖 POI所以项目里如果已经有 POI 依赖一定要统一版本。EasyExcel 3.x 默认依赖 POI 5.x如果你的项目还锁着 POI 4.x运行时大概率会报NoSuchMethodError这类诡异异常。另外从 EasyExcel 3.1.0 开始包名统一为com.alibaba.excel如果你在网上看到的旧教程还是org.apache.poi混着写要注意做适配。2. 导入功能读 Excel从 Listener 说起2.1 最基本的一张表读取EasyExcel 读文件有两种姿势监听器模式和同步读模式。监听器模式适合大文件因为是流式逐行回调同步读适合小文件一把梭返回 List简单直接。监听器模式的核心是一个继承AnalysisEventListenerT的类Slf4j public class UserImportListener extends AnalysisEventListenerUserBO { private static final int BATCH_COUNT 500; private final ListUserBO batchList new ArrayList(); private final BatchSaveService batchSaveService; public UserImportListener(BatchSaveService batchSaveService) { this.batchSaveService batchSaveService; } Override public void invoke(UserBO data, AnalysisContext context) { batchList.add(data); if (batchList.size() BATCH_COUNT) { batchSaveService.batchSave(batchList); batchList.clear(); } } Override public void doAfterAllAnalysed(AnalysisContext context) { if (!batchList.isEmpty()) { batchSaveService.batchSave(batchList); } } }看到了吗invoke方法每读一行就会回调一次所以我们用 BATCH_COUNT 做批量攒批避免一条一条地打数据库。这是导入性能的关键在线导入场景下一万行数据单条 insert 和 500 条批量 insert 的耗时差距能到几十倍。调用的时候EasyExcel.read(inputStream, UserBO.class, new UserImportListener(batchSaveService)) .sheet() .doRead();同步读则更简单适合不那么在乎性能的配置文件导入ListUserBO list EasyExcel.read(fileName) .head(UserBO.class) .sheet() .doReadSync();注意一个细节同步读会一次性把所有行加载进内存文件很大的时候该用监听器还是用监听器不要偷懒。2.2 复杂表头导入headRowNumber 怎么用关键词“easyexcel 复杂的表头导入”是真实业务里高频出现的痛。很多线下表格不是规规矩矩一行表头而是两行、三行甚至前两行还是合并单元格第三行才是真正的列名。这时候如果直接用head(UserBO.class)EasyExcel 会把第一行当成表头最后解析出来的数据全部对不上。解决办法有两个指定表头行数或者使用动态表头。指定表头行数是在read后追加.headRowNumber(3)告诉框架跳过前面 3 行从第 4 行开始读数据EasyExcel.read(inputStream, UserBO.class, listener) .headRowNumber(3) .sheet() .doRead();这个参数在实际业务里特别重要。比如某银行的客户导入模板第一行是大标题“某某银行客户信息批量导入模板”第二行是“制表日期2024-XX-XX”第三行才是“姓名 身份证号 手机号”你解析时 headRowNumber 必须设为 3。还有一种更头疼的情况表头列顺序和实体字段顺序不一致或者模板升级后列顺序变了。这时候可以在实体类头上用ExcelProperty(value 身份证号, index 1)明确指定列索引让字段和列强绑定而不是依赖顺序。我在项目里通常建议所有导入实体都加 index因为业务模板一旦对外发布列顺序不能随便改但代码可能重构显式 index 最保险。2.3 校验与错误处理别让用户只拿到一句“导入失败”导入功能最容易被吐槽的点就是错误提示太模糊。用户传了个 Excel你告诉他“第 3 行数据格式错误”他得自己数半天。真正好用的导入应该是解析完所有行把所有错误行号、字段、原因收集起来要么返回一个错误明细 List要么直接把错误标记写回 Excel 里返给用户下载。我的做法是这样监听器里维护一个ListExcelImportError每解析一行就先做规则校验不通过就记录错误不做中断。等doAfterAllAnalysed时把正确数据批量入库错误数据原样返回。校验规则尽量下沉到字段注解框架内置了对NotNull、Pattern等 JSR-303 注解的支持前提是你引入javax.validation并配置好全局校验器。但 JSR-303 只能做单字段校验跨字段的逻辑比如“开始日期不能晚于结束日期”还是要自己写。更实用的是把错误标记直接做到导出模板里解析完成后把原始 Excel 读成表头在下一行按行号写入错误原因颜色标红再通过接口下载给业务方。这样就完成了从“导入失败”到“修改后再传”的正向闭环业务方体验会好非常多。3. 导出功能从数据到表格的完整套路3.1 基础导出注解 多 Sheet导出相比导入要简单一些核心是实体注解的準确性。一个典型的导出模型Data public class OrderExportBO { ExcelProperty(value 订单号, order 0) private String orderNo; ExcelProperty(value 下单时间, order 1) DateTimeFormat(yyyy-MM-dd HH:mm:ss) private Date orderTime; ExcelProperty(value 金额, order 2) NumberFormat(0.00) private BigDecimal amount; ExcelProperty(value 状态, order 3) private String status; ColumnWidth(20) private String remark; }写入EasyExcel.write(response.getOutputStream(), OrderExportBO.class) .sheet(订单明细) .doWrite(orderList);多 Sheet 导出时要改用ExcelWriter避免一个doWrite只能写一张 sheet 的局限try (ExcelWriter writer EasyExcel.write(response.getOutputStream()).build()) { WriteSheet sheet1 EasyExcel.writerSheet(上海订单).head(OrderExportBO.class).build(); WriteSheet sheet2 EasyExcel.writerSheet(北京订单).head(OrderExportBO.class).build(); writer.write(shanghaiList, sheet1); writer.write(beijingList, sheet2); }这里有个小坑EasyExcel.write里传OutputStream时如果后续代码有异常流必须被正确关闭否则用户下载下来的 Excel 文件会损坏。用 try-with-resources 配合实现了Closeable的ExcelWriter是最省心的做法。3.2 复杂表头导出合并单元格的终极解法热搜词里一直有人搜“easyexcel 复杂的表头导入”其实导出同样逃不掉复杂表头。需求往往是这样的统计报表第一行有“部门”和“成员”两个大分类下面再细分“姓名、工号、职位、入职时间”。注解里写死字段名可以做到但是合并单元格要靠自定义策略。EasyExcel 提供了一个CellWriteHandler接口可以在写入单元格时干预样式和合并行为。实现一个通用合并策略public class ExcelMergeWriteHandler implements CellWriteHandler { private final int[] mergeColumnIndex; private final int mergeRowIndex; public ExcelMergeWriteHandler(int mergeRowIndex, int[] mergeColumnIndex) { this.mergeRowIndex mergeRowIndex; this.mergeColumnIndex mergeColumnIndex; } Override public void afterCellDispose(WriteSheetHolder writeSheetHolder, WriteTableHolder writeTableHolder, ListWriteCellData? cellDataList, Cell cell, Head head, Integer relativeRowIndex, Boolean isHead) { if (isHead) { return; } Sheet sheet writeSheetHolder.getSheet(); int currentRow cell.getRowIndex(); int currentCol cell.getColumnIndex(); // 根据当前值和上一行值判断是否需要合并 String currentValue cell.getStringCellValue(); Cell upCell sheet.getRow(currentRow - 1) null ? null : sheet.getRow(currentRow - 1).getCell(currentCol); String upValue upCell null ? : upCell.getStringCellValue(); if (currentValue ! null currentValue.equals(upValue)) { // 合并当前单元格和上一行同列单元格 sheet.getMergedRegions().stream() .filter(region - region.containsRow(currentRow - 1) region.containsColumn(currentCol)) .findFirst() .ifPresent(region - { sheet.removeMergedRegion(sheet.getMergedRegions().indexOf(region)); sheet.addMergedRegion(new CellRangeAddress( region.getFirstRow(), currentRow, region.getFirstColumn(), region.getLastColumn())); }); } } }这段代码的逻辑是相邻行同列值相同时把当前单元格和上一行已合并的区域合并起来。实际使用时要注意合并后单元格的值只保留左上角单元格的值所以千万不能对每一行都去 setCellValue否则会错乱。如果你觉得自定义 handler 太难维护还有一个折中方案用动态表头 List 写两行表头然后对表头行做一次固定合并。这种方式写死合并区域代码简单但灵活性差一点。我的建议是报表导出用自定义 MergeHandler因为列值合并的规则每个月都可能变模板写死反而更痛苦。3.3 导出时的高频细节冻结、序号、下拉、锁定一个都不能少这一节基本把热搜词里那几个高频问题全部覆盖了也都是我在真实项目中被业务方反复要求过的功能点。3.3.1 冻结列表头不滚前几列不丢冻结功能用 POI 底层 API 就能做。EasyExcel 在WriteSheet建立后可以通过writeSheet.getSheet()拿到底层 sheet 对象然后调用createFreezePane。ExcelWriter writer EasyExcel.write(fileName).build(); WriteSheet writeSheet EasyExcel.writerSheet(数据).build(); writer.write(dataList, writeSheet); // 写完后获取底层sheet做冻结 Sheet sheet writeSheet.getSheet(); sheet.createFreezePane(1, 0); // 冻结第一列 writer.finish();createFreezePane(1, 0)的第一个参数是冻结左侧列数第二个是冻结顶部行数。业务方常说“要冻结前两列和表头”那就是createFreezePane(2, 1)。注意这个方法必须在writer.finish()之前调用否则文件已经写出再冻结就无效了。3.3.2 序号列别往数据库塞序号导出时经常要加一列“序号”最直接的做法是在实体类加一个rownum字段把数据 List 遍历一遍设置i 1。但既然用了 EasyExcel更优雅的方式是写一个简单的CellWriteHandlerpublic class SequenceWriteHandler implements CellWriteHandler { Override public void afterCellDispose(WriteSheetHolder writeSheetHolder, WriteTableHolder writeTableHolder, Cell cell, Head head, Integer relativeRowIndex, Boolean isHead) { if (isHead) { return; } if (cell.getColumnIndex() 0) { cell.setCellValue(relativeRowIndex 1); } } }然后在write时注册EasyExcel.write(response.getOutputStream(), OrderExportBO.class) .registerWriteHandler(new SequenceWriteHandler()) .sheet(订单) .doWrite(orderList);只要第一列是序号不管数据量多大相对行号加一就是正确的序号完全避免在内存里再生成一套带序号的数据副本。3.3.3 下拉框单选可以复选别想了“easyexcel 支持下拉框复选吗”——不支持。Excel 原生下拉数据验证本身就是单选EasyExcel 没有封装下拉框注解POI 的DataValidation也只能做单选。所以如果你看到有人问复选答案很明确要么用前端交互做多选要么放弃下拉框。单值下拉还是经常要做的。实现思路是先用 EasyExcel 把数据写到ByteArrayOutputStream拿到底层 Workbook 后再用 POI 的DataValidationHelper添加下拉数据验证ByteArrayOutputStream out new ByteArrayOutputStream(); ExcelWriter writer EasyExcel.write(out).build(); WriteSheet writeSheet EasyExcel.writerSheet(数据).build(); writer.write(dataList, writeSheet); writer.finish(); Workbook workbook writeSheet.getSheet().getWorkbook(); Sheet sheet workbook.getSheetAt(0); DataValidationHelper helper sheet.getDataValidationHelper(); DataValidationConstraint constraint helper.createExplicitListConstraint( new String[]{启用, 停用, 待审核}); CellRangeAddressList addressList new CellRangeAddressList(1, 500, 5, 5); DataValidation validation helper.createValidation(constraint, addressList); validation.setShowErrorBox(true); sheet.addValidationData(validation);这里有几个关键细节行范围要留足余量。比如模板数据可能涨到几百行你就给1-500范围宁宽勿窄否则后面新增的行没有下拉。setShowErrorBox(true)能保证用户输入不在选项内时 Excel 弹提示这是业务方的硬性要求。下拉项如果超过几十个直接用createExplicitListConstraint会把公式撑爆Excel 的限制是 255 个字符。这时候要改用隐藏 Sheet 名称引用把选项放在隐藏 sheet 里再通过名称管理器引用这也是最后一步再提的方案。3.3.4 工作表保护与部分列锁定这个需求我在做财务类报表时碰到过很多次表里大部分列是计算好的公式不允许用户随便改但有两三列需要填写“备注”“确认人”必须开放编辑。对应的就是热搜词里说的 “sheet.protectSheet 设置了就锁定了全局style.setLocked(false) 实现部分列可编辑”。原理是Excel 里一个单元格是否可编辑由两个条件共同决定一是工作表处于保护状态protectSheet二是单元格样式里的locked属性。默认情况下所有单元格 locked 都是 true所以只要一protectSheet(密码)整张表全锁死。要实现部分列可编辑必须先把要开放的列设置为 lockedfalse。在 EasyExcel 里可以通过自定义CellWriteHandler实现public class UnlockColumnHandler implements CellWriteHandler { private final int[] editableColumns; public UnlockColumnHandler(int[] editableColumns) { this.editableColumns editableColumns; } Override public void afterCellDispose(WriteSheetHolder writeSheetHolder, WriteTableHolder writeTableHolder, Cell cell, Head head, Integer relativeRowIndex, Boolean isHead) { Workbook workbook writeSheetHolder.getSheet().getWorkbook(); CellStyle unlockStyle workbook.createCellStyle(); unlockStyle.setLocked(false); for (int col : editableColumns) { if (cell.getColumnIndex() col) { cell.setCellStyle(unlockStyle); } } } }然后在写完数据后加上Sheet sheet writeSheet.getSheet(); sheet.protectSheet(pwd123);这样用户打开文件时未设置 unlock 的列全部只能看不能点只有指定列可以编辑。要注意unlockStyle会覆盖原有样式所以如果那列本来有背景色、边框需要把原样式复制过来再改 locked 属性不要让样式丢失。3.3.5 列宽、日期格式、数字格式这些属于看着不起眼、用户体验影响很大的细节。ColumnWidth标注在实体类上对导出全局生效但导入场景下对模板生成也有效果。日期格式用DateTimeFormat数字格式用NumberFormat。我特别提醒一句金额字段千万别用Double一旦超过 16 位精度就出问题导出给财务的东西必须用BigDecimal然后用NumberFormat(0.00)固定两位小数。否则用户看到 1.999999999第一反应就是你们的系统有 bug。3.4 大数据量导出别一把梭前面说 EasyExcel 省内存那是相对于 POI 的 DOM 模式而言。但是如果你把数据库十万条记录一次性select出来放进 List再传给 EasyExcel那内存照样扛不住。大数据量导出的正确姿势是分批查询 分批写入。ExcelWriter writer EasyExcel.write(response.getOutputStream()) .head(OrderExportBO.class) .build(); WriteSheet writeSheet EasyExcel.writerSheet(订单数据).build(); int pageSize 5000; int pageNum 1; while (true) { ListOrderExportBO pageData orderService.queryPage(pageNum, pageSize); if (pageData.isEmpty()) { break; } writer.write(pageData, writeSheet); pageData.clear(); pageNum; } writer.finish();这里每次只查 5000 条写入后立刻清空列表内存占用就是这 5000 条记录的量级。如果单 Sheet 行数超过 100 万Excel 打开会卡所以更稳妥的做法是按 50 万行切分 Sheet逻辑大同小异无非是EasyExcel.writerSheet(第1部分)、EasyExcel.writerSheet(第2部分)。还有一个常见坑导出接口要用response.getOutputStream()时需要提前设置Content-Disposition并且doWrite或writer.finish()后才能 close 流。顺序写反比如先关了 response 流再 finish文件会不完整。我的习惯是全部交给 try-with-resources 管理不手动去关。4. 常见问题与排查技巧实录4.1 空行和一列都为空带来的噩梦导入时如果 Excel 中有整行空白EasyExcel 默认ignoreEmptyRow为 true会跳过处理。但有时候数据中间夹着空行你又设置ignoreEmptyRow(false)去强制解析就会遇到AnalysisException或者读出来一列都是 null。解决思路是模板层面禁用空行Excel 里的“数据验证”配合条件格式提示。代码层面在invoke里做全员非空判断如果整行字段都为 null直接 return不进批量 List。我用得最多的还是后者入侵最小也不影响业务方填表习惯。4.2 日期、数字、金额的格式转换坑导入场景里最常见的 bug 是“日期读出来变成一串数字”或者“金额读出来精度少了两位”。前者多半是因为没加DateTimeFormat注解EasyExcel 把日期列按默认数字方式处理了。后者是因为实体字段写了Double而不是BigDecimal。建议日期字段统一用DateDateTimeFormat就算模板里是文本日期也能解析。金额字段统一用BigDecimalNumberFormat。单元格是文本格式时BigDecimal字段会读取失败提示NumberFormatException可以在模板中把该列设置为“文本”或统一走自定义转换器这属于进阶方案有空单独写一篇。4.3 POI 版本冲突 / NoClassDefFoundError前面提过EasyExcel 3.x 依赖 POI 5.x。项目里如果引了 POI 4.x 或者更老的poi-ooxml运行时经常爆NoSuchMethodError。排查方法很简单看报错栈顶是否在org.apache.poi.ss.usermodel或者org.apache.poi.xssf包下十有八九是版本问题。解决办法是用 Maven 的dependencyManagement把 POI 版本统一到 EasyExcel 需要的版本或者干脆去掉项目里显式声明的 POI 依赖EasyExcel 传递依赖会自动引入。4.4 临时文件清理引发的 FileNotFoundExceptionEasyExcel 在写大文件时会在临时目录下生成缓存文件。有时导出接口跑到一半报FileNotFoundException不是数据问题而是 Linux 服务器清理临时文件或者程序重启导致临时文件被删。解决建议导出时指定可靠的临时目录System.setProperty(java.io.tmpdir, /data/tmp)或者在EasyExcel.write时直接指定ExcelTypeEnum.XLSXxls 格式不支持流式写入大文件只能 xlsx。异常发生时调用writer.finish()/writer.close()尽快释放临时文件资源。4.5 复杂表头读取时第一行数据消失接 2.2 的场景不少同学设置headRowNumber(3)后第一行数据还是丢了。原因是模板里表头真正占的行数少于 3或者表头区域存在合并单元格导致行列结构发生变化。我的排查经验是先不加 headRowNumber 试读把 sheet 内容打印出来确认“数据第一行实际在第几行”再回填这个数字。用模板下载功能时也要在模板里固定写好合并单元格格式别让业务方自己改动表头。4.6 常见问题速查表症状大概率原因解决办法导出文件损坏Excel 提示修复OutputStream 提前关闭或未 finishtry-with-resources 管理 ExcelWriter读取日期变成数字缺少DateTimeFormat实体字段加注解读取金额精度丢失字段类型是 Double改用 BigDecimal NumberFormatNoSuchMethodErrorPOI 版本冲突统一 POI 版本写入时临时文件被占用tmp 目录被清理指定固定 tmp dir复杂表头数据错位headRowNumber 配置不对打印解析内容实际确认行数下拉框选项不生效下拉范围写错扩大 CellRangeAddressList 范围设置了 protectSheet 但所有列还可编辑忘了给单元格应用 locked 样式先设置 locked再保护说实话我在项目里最深的体会是导入导出这件事技术栈选型只占三成剩下七成都在细节里。同样是 EasyExcel有人写出来就是一套异常处理、格式控制、错误反馈都齐全的完整模块有人写出来就是能用但一上线就被业务方吐槽的资源黑洞。差别就在于你是否认真处理了空行、格式、版本、临时文件这些边缘情况。最后分享一个小技巧如果你们公司有多个系统都在做导入导出建议抽一个excel-common模块把监听器、合并策略、解锁策略、模板下载、错误返回这些公共能力沉淀下来。不同系统的业务字段千差万别但导入导出的骨架永远是那一套。把这些通用逻辑封装好后新系统接导入导出功能开发时间基本能从两三天压缩到半天而且稳定性会高很多。这也是 EasyExcel 这类工具带给我们的最大价值——它把底层复杂性挡住了剩下的就看你能不能把上层套路做扎实。