报表导出导入这个需求几乎每个后台管理系统都躲不掉。早些年我用POI硬刚百万级数据结果GC频繁、内存爆掉被运维约谈过好几次。后来换成EasyExcel情况才好转。这篇文章就把我在SpringBoot项目里整合EasyExcel做高性能报表导入导出的完整经验写出来从选型思路、代码实现到性能调优和踩坑记录一次性说清楚。1. 项目整体设计与技术选型思路1.1 为什么放弃原生POI改用EasyExcel很多初学者一上来就用POI的HSSFWorkbook或XSSFWorkbook写导出数据量小的时候没什么感觉一旦到了几万行内存占用立刻飙升。核心原因在于POI的XSSFWorkbook采用的是DOM模型会把整个Excel文档一次性加载到内存里构建对象树。想象一下一个包含50万行、30列数据的Sheet每个单元格都要在内存里创建对应的Cell对象这中间的开销远比你想象的大。实测下来用POI导出50万行数据JVM堆内存至少要给到2GB以上而且稍不注意就OOM。EasyExcel重写了POI对07版Excel的解析逻辑核心优势有三个注解驱动模型实体类和Excel列之间直接映射代码量大幅减少读写过程基于SAX事件驱动不会把整个文件载入内存自带文件分片写入机制数据边生成边写盘内存占用极低我的选择理由很简单EasyExcel底层仍然是POI的解析包但不走DOM路线而是自己实现了SAX相关的AnalysisExcel逻辑。也就是说你保留了POI的能力但绕开了POI的内存瓶颈。这里说个题外话如果你只是导出一个几十行的配置表POI完全够用杀鸡不必用牛刀。但凡是数据量可能超过1万行的场景我建议直接上EasyExcel别等出问题再重构。1.2 适用场景与使用边界分析EasyExcel适合的典型场景包括业务报表导出比如订单明细、交易流水、用户列表批量导入比如Excel维护商品信息、批量初始化账号对账文件生成比如和第三方渠道按月对账数据迁移从旧系统导出历史数据归档但并不适合所有场景。比如你需要在导出前对大量数据做复杂的内存计算或者需要在Excel内生成复杂的图表、数据透视表那EasyExcel并不擅长这些还是得回到POI或者用模板引擎预生成。另外需要明确一点EasyExcel强调的是高性能读写Excel文件它不是报表引擎。报表引擎负责数据的聚合计算、可视化呈现EasyExcel只负责把结果数据高效地写进Excel或者从Excel高效地读出来。1.3 版本选择与环境预检我用的是目前生产环境验证过的组合组件版本说明SpringBoot2.7.x2.x系列稳定和EasyExcel兼容性好EasyExcel3.3.x3.x系列API更友好推荐使用POI5.2.xEasyExcel 3.x内部依赖POI 5.xJDK83.x版本要求JDK8及以上这里要注意一个版本坑EasyExcel 2.x和3.x的API差异很大网上的教程很多是2.x的老写法照搬会报方法不存在。我建议直接用3.xFastExcel工具类已经内置了大部分核心操作不需要写那么多样板代码。另外poi的版本不建议自己额外引入覆盖EasyExcel自带依赖管理强制覆盖版本容易引发莫名其妙的兼容问题。2. 基础工程搭建与核心依赖配置2.1 Maven依赖引入细节以SpringBoot项目为例在pom.xml里加入EasyExcel依赖。很多人直接复制下面这段就走dependency groupIdcom.alibaba/groupId artifactIdeasyexcel/artifactId version3.3.2/version /dependency这个写法在大多数情况下没问题但在实际项目里如果你们公司有自己的BOMBill of Materials统一管理第三方依赖版本注意不要和BOM里的POI版本冲突。我的做法是单独指定EasyExcel版本并且不额外引入poi-ooxml避免重复依赖。同时如果项目里用了hutool的Excel工具也要注意冲突。hutool的ExcelUtil底层是POI和EasyExcel共用POI类库时某些版本会产生NoSuchMethodError。我踩过一次后来把hutool的excel模块从依赖里排除了才解决。2.2 实体模型与注解配置导入导出第一个核心工作是把Excel列和Java实体字段做映射。EasyExcel提供了注解和无注解两种方式我强烈推荐注解方式代码可读性和维护性都更好。一个标准模型定义长这样Data public class OrderExcelModel { ExcelProperty(value 订单号, index 0) private String orderNo; ExcelProperty(value 下单时间, index 1) private Date orderTime; ExcelProperty(value 订单金额, index 2) private BigDecimal amount; ExcelProperty(value 收货人, index 3) private String receiverName; ExcelProperty(value 收货电话, index 4) private String receiverPhone; }index很好理解就是列索引从0开始。如果不指定indexEasyExcel会根据value名称去匹配表头这时表头名称和注解里的value必须完全一致包括空格。这里有几个细节值得注意Date类型字段默认导出格式是时间戳数字需要配合DateTimeFormat注解指定格式DateTimeFormat(yyyy-MM-dd HH:mm:ss) private Date orderTime;BigDecimal导出时默认会显示为科学计数法对Excel用户很不友好建议格式化NumberFormat(#.##) private BigDecimal amount;实体字段建议全部用包装类型别用基本类型。原因很简单导出时如果为null基本类型会输出默认值0容易误导报表使用者导入时Excel单元格为空转换基本类型也可能抛异常。2.3 通用工具类封装实际项目中导出导入绝不只一个模块用所以工具类是必须的。我封装了一个ExcelUtils把最常用的三个操作提炼成静态方法按模板导出、按自定义头导出、异步导入解析。public class ExcelUtils { public static T void writeExcel(HttpServletResponse response, String fileName, ClassT clazz, ListT dataList) throws IOException { setResponseHeader(response, fileName); EasyExcel.write(response.getOutputStream(), clazz) .sheet(数据) .doWrite(dataList); } public static T void writeExcelWithHead(HttpServletResponse response, String fileName, ListListString headList, ListListObject dataList) throws IOException { setResponseHeader(response, fileName); EasyExcel.write(response.getOutputStream()) .head(headList) .sheet(数据) .doWrite(dataList); } public static T void readExcel(MultipartFile file, ClassT clazz, AnalysisEventListenerT listener) throws IOException { EasyExcel.read(file.getInputStream(), clazz, listener) .sheet() .doRead(); } private static void setResponseHeader(HttpServletResponse response, String fileName) throws UnsupportedEncodingException { response.setContentType(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet); response.setCharacterEncoding(utf-8); String encodedFileName URLEncoder.encode(fileName, UTF-8).replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment;filename*utf-8 encodedFileName); } }里面的setResponseHeader特别关键很多新手直接写filename文件名.xlsx一旦文件名包含中文浏览器下载时就会出现乱码。这里用URLEncoder.encode做了编码转换并且采取filename*格式兼容大多数主流浏览器。3. 导出功能核心实现与性能优化3.1 大数据量导出分批写入与内存控制先看一个反面教材也是很多新手常犯的错误// 错误示例 ListOrderExcelModel allData orderMapper.selectAll(); // 一次性查50万条 EasyExcel.write(outputStream, OrderExcelModel.class).sheet().doWrite(allData);这段代码的问题在于selectAll()把50万条记录全加载到内存了即便EasyExcel写Excel再省内存你前面查出来的List本身就已经占了很大一块堆空间。数据量到达一定规模OOM几乎是必然的。正确做法是分批查询、分批写入public void exportLargeData(HttpServletResponse response) throws IOException { setResponseHeader(response, 订单明细导出); ExcelWriter excelWriter null; try { excelWriter EasyExcel.write(response.getOutputStream(), OrderExcelModel.class) .build(); WriteSheet writeSheet EasyExcel.writerSheet(订单明细).build(); // 分页查询每页1万条写一批释放一批 int pageSize 10000; int pageNum 1; ListOrderExcelModel pageData; do { pageData orderMapper.selectPage(pageNum, pageSize); if (CollectionUtils.isEmpty(pageData)) { break; } excelWriter.write(pageData, writeSheet); pageData.clear(); // 帮助GC回收 pageNum; } while (pageData.size() pageSize); } finally { if (excelWriter ! null) { excelWriter.finish(); } } }为什么这么写每次只从数据库取1万条占用的Java堆内存可控excelWriter.write(pageData, writeSheet)把内存中的数据转成Excel文件内容流式写到磁盘或网络流写完即可释放pageData.clear()主动把List引用置空让GC及时回收这里补充一个点ExcelWriter用完必须调用finish()否则会残留临时文件或者输出流不完整。我把finish()放在finally块里保证必定执行。3.2 动态列导出多Sheet与自定义表头固定实体类的导出只能处理列结构固定的表格现实业务里有大量场景需要动态生成表头。比如一个销售趋势报表列是1月、2月、3月...12月这个列集合是运行时根据条件生成的没法预先定义实体类。这时候就用到动态表头APIpublic void exportDynamicHead(HttpServletResponse response, ListString monthList, MapString, ListObject rowDataMap) throws IOException { setResponseHeader(response, 销售趋势报表); ListListString head new ArrayList(); // 第一列固定 head.add(Collections.singletonList(店铺名称)); // 动态月份列 for (String month : monthList) { head.add(Collections.singletonList(month 销售额)); } ListListObject rows new ArrayList(); for (Map.EntryString, ListObject entry : rowDataMap.entrySet()) { ListObject row new ArrayList(); row.add(entry.getKey()); row.addAll(entry.getValue()); rows.add(row); } EasyExcel.write(response.getOutputStream()) .head(head) .sheet(销售数据) .doWrite(rows); }注意动态表头模式下head是一个ListListString每个内层List代表一列。如果某列需要二级表头就在内层List里放多个字符串EasyExcel会自动合并单元格。比如head.add(Arrays.asList(2024年度, 第一季度));这会在表头显示2024年度合并单元格下挂第一季度。多级表头在生成复杂统计报表时非常实用。再说一个多Sheet场景。假设需要把12个月的数据分别写到12个Sheet里ExcelWriter excelWriter EasyExcel.write(response.getOutputStream(), OrderExcelModel.class).build(); for (int i 1; i 12; i) { String sheetName i 月; WriteSheet writeSheet EasyExcel.writerSheet(i - 1, sheetName).build(); ListOrderExcelModel monthData orderMapper.selectByMonth(i); excelWriter.write(monthData, writeSheet); } excelWriter.finish();这里有个容易踩的坑writerSheet的第一个参数是Sheet的序号从0开始不传序号的话重复同名Sheet会互相覆盖。3.3 导出时对字段进行自定义处理导出场景经常会遇到实体字段不能直接展示需要加工的情况。比如订单状态在数据库里是0/1/2报表里必须显示待支付/已支付/已取消再比如手机号中间四位要脱敏。有两种处理方式方式一在实体里增加一个临时展示字段用ExcelProperty注解标注业务层去填充ExcelProperty(value 订单状态, index 5) private String statusDesc;这种方式直观简单我大部分项目都是这样做的。缺点是实体类会多出不属于数据库表的冗余字段。方式二使用Converter转换器。定义一个枚举转换器public class OrderStatusConverter implements ConverterInteger { Override public Class? supportJavaTypeKey() { return Integer.class; } Override public CellDataTypeEnum supportExcelTypeKey() { return CellDataTypeEnum.STRING; } Override public Integer convertToJavaData(ReadConverterContext? context) { // 导入时Excel里的已支付转换为1 String statusStr context.getReadCellData().getStringValue(); return 已支付.equals(statusStr) ? 1 : 0; } Override public WriteCellData? convertToExcelData(WriteConverterContextInteger context) { // 导出时数字1转换为已支付 Integer status context.getValue(); String value status ! null status 1 ? 已支付 : 已取消; return new WriteCellData(value); } }然后在实体字段上标注ExcelProperty(value 订单状态, index 5, converter OrderStatusConverter.class) private Integer status;两种方案使用场景不同。如果只是导出时展示加工方式一更轻量如果同一个字段的导入导出都要加工方式二更优雅避免在多个业务层重复写if-else转换逻辑。3.4 导出时锁定表头与自适应列宽内存流式写入时用户拿到Excel第一反应是表头在哪。EasyExcel默认写出的表格没有冻结窗格数据量大时往下翻就看不到表头了。通过WriteSheet设置冻结窗格WriteSheet writeSheet EasyExcel.writerSheet(订单明细) .needHead(Boolean.TRUE) .build();但这只能控制是否输出表头行真正的冻结窗格需要依赖Sheet的createFreezePane。EasyExcel没有直接暴露这个API可以在afterAllHandlers里获取POI原生的Sheet对象设置WriteSheet writeSheet EasyExcel.writerSheet(订单明细) .registerWriteHandler(new AbstractRowWriteHandler() { Override public void afterSheetCreate(WriteWorkbookHolder writeWorkbookHolder, WriteSheetHolder writeSheetHolder) { org.apache.poi.ss.usermodel.Sheet sheet writeSheetHolder.getSheet(); // 冻结第一行 sheet.createFreezePane(0, 1); } }) .build();列宽方面EasyExcel默认列宽固定中文内容很容易显示不全。如果数据量不大几千行以内可以直接用Sheet设置列宽比如设置第0列宽20字符registerWriteHandler(new AbstractColumnWidthStyleStrategy() { Override protected void setColumnWidth(WriteSheetHolder writeSheetHolder, ListWriteCellData? cellDataList, Cell cell, Boolean isHead) { // 也可以按内容长度自动计算但注意大数据量下会拖慢速度 } });这里要提醒按内容长度自适应的列宽策略不要用在十万级以上的大数据量导出因为每次写一行都要遍历计算宽度性能会断崖式下降。大数据量场景要么固定列宽要么干脆不做自适应。4. 导入功能核心实现与防坑指南4.1 监听器机制与逐行处理原理导入比导出复杂的地方在于数据校验失败需要精确定位到行号、列号数据量大了不能一次性全部load进内存业务校验逻辑和文件解析逻辑要解耦。EasyExcel的导入核心是监听器。每个AnalysisEventListener维护自己的业务处理逻辑它逐行被回调而不是全部读完后一次性给你一个List。一个完整的导入监听器长这样Slf4j public class OrderImportListener extends AnalysisEventListenerOrderExcelModel { private static final int BATCH_SIZE 1000; private ListOrderExcelModel cache new ArrayList(); private final OrderService orderService; private final ImportResult result; public OrderImportListener(OrderService orderService, ImportResult result) { this.orderService orderService; this.result result; } Override public void invoke(OrderExcelModel data, AnalysisContext context) { // 逐行校验 Integer rowIndex context.readRowHolder().getRowIndex(); String errorMsg validate(data); if (StringUtils.isNotEmpty(errorMsg)) { result.addError(rowIndex, errorMsg); return; } cache.add(data); if (cache.size() BATCH_SIZE) { saveBatch(); } } Override public void doAfterAllAnalysed(AnalysisContext context) { // 剩余不足一批的数据也要入库 saveBatch(); log.info(本次导入完成成功{}条失败{}条, result.getSuccessCount(), result.getErrorCount()); } private void saveBatch() { orderService.batchSave(cache); result.increaseSuccess(cache.size()); cache.clear(); } private String validate(OrderExcelModel data) { if (StringUtils.isBlank(data.getOrderNo())) { return 订单号不能为空; } if (data.getAmount() null || data.getAmount().compareTo(BigDecimal.ZERO) 0) { return 订单金额必须大于0; } return null; } }这段代码的设计思路值得说一下逐行校验错误行直接记录到结果集不影响后续行解析满1000条批量入库减少数据库交互次数解析完成后把不满一批的也入库防止数据丢失导入结果用独立的ImportResult对象收集不污染业务逻辑4.2 导入模板下载与校验机制匹配导入功能必须配套提供一个模板下载功能。用户先下载模板按模板格式填充数据后再上传这样能大幅降低导入报错率。模板下载本质上就是一次空的导出GetMapping(/template) public void template(HttpServletResponse response) throws IOException { setResponseHeader(response, 订单导入模板); ListOrderExcelModel emptyList Collections.emptyList(); EasyExcel.write(response.getOutputStream(), OrderExcelModel.class) .sheet(订单导入) .needHead(Boolean.TRUE) .doWrite(emptyList); }模板里只含表头不包含任何数据行。另外我建议在模板里加一个示例数据行并隐藏掉这样既能引导用户填写格式又不会影响解析需要解析时跳过第一行数据。不过隐藏行容易让用户困惑实践下来效果一般我这里顺便提一句作为参考。还有一点很关键校验逻辑必须和模板的表头完全一致。比如模板里没有订单状态这一列但实体类里status字段加了ExcelProperty(value 订单状态)导入时就会报找到不匹配的头或者干脆所有行都读不出status值。建议导入前先做一次表头校验看Excel模板列头是否符合预期。表头校验可以这样实现public void checkHead(MultipartFile file, ListString expectHead) { try (InputStream inputStream file.getInputStream()) { ExcelReader excelReader EasyExcel.read(inputStream).build(); ReadSheet readSheet EasyExcel.readSheet(0).build(); // 只读取表头 excelReader.read(readSheet); ListString actualHead ... // 通过listener获取第一行 } }业界更常见的做法是直接复用导入监听器在invokeHeadMap回调里拿到表头Map做比对。EasyExcel的AnalysisEventListener里有一个invokeHeadMap(MapInteger, String headMap, AnalysisContext context)方法重写它就能在解析正文之前先校验表头。4.3 大文件导入的IO流处理细节用户上传的Excel文件可能是几十MB的大文件。直接file.getInputStream()没问题但要注意生产环境不敢把最大上传体积调太高一般spring.servlet.multipart.max-file-size设10MB或20MB实际项目中有压缩包上传的场景解压后再解析注意解压后的临时文件要按时间清理导入时建议对文件流做try-with-resources防止流泄漏贴近实战的完整导入接口长这样PostMapping(/import) public R importExcel(RequestParam(file) MultipartFile file) throws IOException { if (file null || file.isEmpty()) { return R.fail(上传文件不能为空); } // 校验文件格式 String fileName file.getOriginalFilename(); if (!fileName.endsWith(.xlsx) !fileName.endsWith(.xls)) { return R.fail(仅支持.xlsx或.xls格式的Excel文件); } ImportResult result new ImportResult(); OrderImportListener listener new OrderImportListener(orderService, result); try (InputStream inputStream file.getInputStream()) { EasyExcel.read(inputStream, OrderExcelModel.class, listener) .sheet() .headRowNumber(1) // 表头占1行正文从第2行开始 .doRead(); } catch (Exception e) { log.error(文件解析异常, e); return R.fail(文件解析失败 e.getMessage()); } return R.ok(result); }这里面headRowNumber(1)的含义一定要理解。如果模板第一行是标题比如订单导入模板第二行才是表头那就要设headRowNumber(2)否则解析会把表头当成数据。4.4 导入数据一致性保障导入不是读出来然后一条条insert这么简单生产环境要保障数据一致性。我的实践是在doAfterAllAnalysed之后再对校验通过的数据做事务性入库处理。具体做法是在业务方法上开启事务Transactional(rollbackFor Exception.class) public void batchSave(ListOrderExcelModel list) { // 批量插入或更新 }但这有个问题上面监听器的saveBatch会分批调用batchSave如果最后一批出了异常前面几批已经提交的数据就不会回滚。针对这个情况有两种方案方案一全量校验通过后再统一入库。先把所有数据读到一个List里然后整体交给事务方法处理。缺点是数据量大时占用内存多和导入的初衷相悖。方案二分批入库并记录批次状态。哪一批失败就重试哪一批错误信息精确到批次。适合导入数据本身互相独立、允许部分成功的场景。实际业务中我常用方案一的小数据量版本限制单次导入文件行数比如最多5000行保证所有数据能一次性加载到内存然后整体事务提交出了任何一条脏数据全部回滚用户重新修改后再导入。这种模式对业务一致性要求高的场景比如财务账目导入是最稳妥的。5. Excel导入导出的性能调优实战5.1 百万数据导出的JVM参数与GC调优生产环境跑大数据量导出JVM参数设置很关键。以导出100万行、每行30列左右的报表为例我的经验参数如下-Xms2048m -Xmx4096m -XX:UseG1GC -XX:MaxGCPauseMillis200简单解释一下EasyExcel是流式写出堆内存占用相对可控4GB足够应对百万级导出G1垃圾回收器相比CMS更适合这种大对象持续产生-短期存活的场景停顿时间更稳定MaxGCPauseMillis200限制GC最大停顿避免导出过程中接口响应时间出现长尾如果服务本身堆内存无法给到4GB那就得从代码层面继续优化把导出逻辑扔到MQ里异步处理生成文件后上传到对象存储再给用户一个下载链接。这是另一个维度的话题但实际项目中非常常见。5.2 导入速度优化批量插入与并行解析导入性能的瓶颈通常在数据库写入而不是文件解析。EasyExcel解析一个10万行的xlsx文件纯解析也就几秒但如果你一条一条insert10万条数据可能要跑二十几分钟。批量插入是标配优化手段Transactional public void batchSave(ListOrderExcelModel list) { // 用MyBatis的foreach批量插入分批1000条执行一次 orderMapper.batchInsert(list); }insert idbatchInsert parameterTypelist insert into t_order (order_no, order_time, amount, receiver_name, receiver_phone) values foreach collectionlist itemitem separator, (#{item.orderNo}, #{item.orderTime}, #{item.amount}, #{item.receiverName}, #{item.receiverPhone}) /foreach /insert注意MyBatis的foreach拼接SQL有长度限制一次1000条比较安全5000条以上容易触发数据库max_allowed_packet超限。数据库层面也有优化空间比如导入时可以临时关闭唯一索引检查导完再开启。但生产环境不要这么做容易造成索引不一致风险大于收益。更稳妥的作法是直接用INSERT IGNORE或者ON DUPLICATE KEY UPDATE来做去重写入但注意这只适用于MySQL场景。另一种导入优化思路是并行解析。EasyExcel官方不推荐多线程读同一个Sheet因为Sheet内部解析是有状态的。但多个文件可以并行解析ExecutorService executorService Executors.newFixedThreadPool(4); for (MultipartFile file : files) { executorService.submit(() - { ImportResult result new ImportResult(); try (InputStream inputStream file.getInputStream()) { EasyExcel.read(inputStream, OrderExcelModel.class, new OrderImportListener(orderService, result)) .sheet() .doRead(); } return result; }); }这种方式适合一次上传多个Excel文件的场景例如按分店批量上传注意线程池大小不要超过CPU核数否则频繁上下文切换反而变慢。5.3 内存对比实测POI与EasyExcel的差异我早前在一台4核8G的测试机上做过一次对比实验导出30万行、25列数据方案堆内存峰值耗时是否OOMPOI XSSFWorkbook2.4GB38秒否接近临界POI SXSSFWorkbook900MB22秒否EasyExcel320MB18秒否这个数据不完全科学因为机器状态、JVM参数不同都会影响结果但趋势是明确的EasyExcel的内存占用约为POI XSSF的1/7速度反而更快。又测了导入场景EasyExcel读一个10万行xlsx文件堆内存峰值大概160MBPOI XSSF读同样文件至少要1.2GB差距悬殊。这也是为什么在线导入功能在大数据量场景下几乎只能选择EasyExcel类方案的原因。6. 实践中的常见问题与排查经验6.1 中文文件名下载乱码问题这个问题几乎每个项目都会遇到而且排查起来很容易忽略。浏览器下载文件时对Content-Disposition头的解析规则很挑剔早期的写法response.setHeader(Content-Disposition, attachment; filename fileName);只要文件名是中文Chrome和Firefox大概率乱码。是因为这个Header只能包含ASCII字符中文未经编码直接放进去就会出问题。正确做法已经在上文工具类里写过了再重复强调一次String encodedFileName URLEncoder.encode(fileName, UTF-8).replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment;filename*utf-8 encodedFileName);两个要点URLEncoder.encode会把空格变成而Header里会被解析为空格所以必须replaceAll(\\, %20)转回空格编码filename*是RFC 5987规范格式为utf-8编码后的文件名前后都不能错6.2 Date类型与Excel单元格格式的时区偏差导出的时间字段用户反馈和数据库里的时间差了8小时。排查后发现是POI底层处理Date类型时读取了本地时区。测试环境和服务器时区不一致导致导出Excel中看到的日期时间有偏差。解决方案有两个一是实体字段统一用字符串时间ExcelProperty(value 下单时间, index 1) private String orderTimeStr; // 业务层格式化好再放进来二是设置全局时区TimeZone.setDefault(TimeZone.getTimeZone(Asia/Shanghai));我建议生产环境直接用方案一因为方案二会全局影响JVM所有时间处理逻辑可能引发其他问题属于解决一个问题引入另一个问题。6.3 导入时空行与空白Sheet的兜底处理用户上传的Excel经常有莫名其妙的空行尤其从某个系统导出的文件末尾可能带几十个空行。如果监听器不做处理空行也会触发invoke回调虽然实体类字段全部为null但依然会走一遍校验逻辑产生一堆无意义的错误记录。兜底处理很关键在invoke方法头部拦截Override public void invoke(OrderExcelModel data, AnalysisContext context) { if (data null || isAllFieldNull(data)) { return; } // 正常业务逻辑 } private boolean isAllFieldNull(OrderExcelModel data) { return StringUtils.isAllBlank(data.getOrderNo(), data.getReceiverName()) data.getAmount() null data.getOrderTime() null; }注意isAllBlank是Hutool的方法如果项目没引Hutool就手动判断各个字段。这里还有个细节HTTP请求里上传的IE浏览器版本很低时MultipartFile的原始文件名获取会有差异IE全家桶对filename和filename*的支持很烂如果你们的系统还需要兼容老旧浏览器建议前端先做一次文件名校验再上传。6.4 并发导出的连接池与线程池配置报表导出功能通常也是高并发入口多个用户同时点导出后端如果处理不当很容易打垮数据库。我的建议导出接口使用异步线程池前端轮询下载状态文件生成好再提示下载限制导出接口的并发数用信号量控制同时导出任务不超过3~5个数据库连接池HikariCP的maximum-pool-size要结合导出占用连接计算。一个批量查询导出会占用一个数据库连接很长时间如果连接池只有10个连接5个用户在导出剩下5个连接要支撑所有其他业务请求极易连接池耗尽通过Semaphore做并发控制的简单示例private final Semaphore exportSemaphore new Semaphore(3); public void export(HttpServletResponse response, ExportQuery query) throws IOException { if (!exportSemaphore.tryAcquire()) { throw new BusinessException(当前导出任务过多请稍后再试); } try { doExport(response, query); } finally { exportSemaphore.release(); } }这个示例是同步导出的做法更友好的体验是异步导出然后推送下载链接核心思路是一样的限制并发数量保护下游资源。6.5 问题速查表现象可能原因解决方案导出Excel打不开提示损坏输出流没有调用finish()确保finally中调用excelWriter.finish()中文表头变乱码Content-Disposition头编码问题使用filename*并URL编码导入时时间少了8小时JVM默认时区和预期不一致使用字符串时间字段或显式设置时区导入只有表头没有数据headRowNumber设置不对检查模板前几行调整headRowNumber大批量导出内存飙升一次性查询全量数据到内存分页查询分批写入导入时实体字段全部为nullExcel列索引和实体index不匹配检查模板表头顺序和ExcelProperty的index对齐首行数据被当成表头模板第一行是标题行headRowNumber(2)7. 实际项目应用的经验总结最后分享几个我在这类项目里沉淀下来的实操经验不是理论推断是真实踩坑换来的。第一个关于项目架构不要把导入导出逻辑塞在Controller里。我最初图省事直接在Controller写了个两三百行的方法后来需求一改就痛苦。现在我的做法是抽出一个独立的ReportService层Controller只负责接收参数和返回结果文件处理、数据校验、业务落库全在Service层管理。这样单个导出导入方法能控制在让后继者看懂的范围里。第二个关于日志导入导出场景必须打日志而且要打印行号和错误原因。用户反馈我上传的文件导不进去如果没有日志排查全靠猜。我在监听器里每个出错行都会log.warn(第{}行导入失败{}, rowIndex, errorMsg)运维出问题一查日志立刻定位。第三个关于产品设计导入前坚持让用户下载模板。很多开发觉得下载模板多此一举实际上模板能规范用户上传格式从源头减少脏数据。模板里我也加了示例行和必填标记红色字体用户的首次成功率非常高。第四个关于测试做导入功能测试用例一定要包含空文件、只有表头、100MB大文件、带空行、带特殊字符、带公式单元格这些边界场景。尤其带公式单元格的场景容易被忽略Excel里某个单元格内容是SUM(A1:A10)直接用EasyExcel读出来拿到的是公式字符串而不是计算结果如果你的业务期望拿值需要在Excel模板上做配合或者接受这个行为。做这类功能不追求代码花哨重点是逻辑严谨、内存可控、边界场景都兜住。这套整合方案我在多个项目上用过导出百万级数据稳定不OOM导入十万级数据校验入库控制在十几秒内生产环境用了两三年没出过大问题。照着这篇文章的思路走你的报表模块也能少走不少弯路。
报表导出导入这个需求几乎每个后台管理系统都躲不掉。早些年我用POI硬刚百万级数据结果GC频繁、内存爆掉被运维约谈过好几次。后来换成EasyExcel情况才好转。这篇文章就把我在SpringBoot项目里整合EasyExcel做高性能报表导入导出的完整经验写出来从选型思路、代码实现到性能调优和踩坑记录一次性说清楚。1. 项目整体设计与技术选型思路1.1 为什么放弃原生POI改用EasyExcel很多初学者一上来就用POI的HSSFWorkbook或XSSFWorkbook写导出数据量小的时候没什么感觉一旦到了几万行内存占用立刻飙升。核心原因在于POI的XSSFWorkbook采用的是DOM模型会把整个Excel文档一次性加载到内存里构建对象树。想象一下一个包含50万行、30列数据的Sheet每个单元格都要在内存里创建对应的Cell对象这中间的开销远比你想象的大。实测下来用POI导出50万行数据JVM堆内存至少要给到2GB以上而且稍不注意就OOM。EasyExcel重写了POI对07版Excel的解析逻辑核心优势有三个注解驱动模型实体类和Excel列之间直接映射代码量大幅减少读写过程基于SAX事件驱动不会把整个文件载入内存自带文件分片写入机制数据边生成边写盘内存占用极低我的选择理由很简单EasyExcel底层仍然是POI的解析包但不走DOM路线而是自己实现了SAX相关的AnalysisExcel逻辑。也就是说你保留了POI的能力但绕开了POI的内存瓶颈。这里说个题外话如果你只是导出一个几十行的配置表POI完全够用杀鸡不必用牛刀。但凡是数据量可能超过1万行的场景我建议直接上EasyExcel别等出问题再重构。1.2 适用场景与使用边界分析EasyExcel适合的典型场景包括业务报表导出比如订单明细、交易流水、用户列表批量导入比如Excel维护商品信息、批量初始化账号对账文件生成比如和第三方渠道按月对账数据迁移从旧系统导出历史数据归档但并不适合所有场景。比如你需要在导出前对大量数据做复杂的内存计算或者需要在Excel内生成复杂的图表、数据透视表那EasyExcel并不擅长这些还是得回到POI或者用模板引擎预生成。另外需要明确一点EasyExcel强调的是高性能读写Excel文件它不是报表引擎。报表引擎负责数据的聚合计算、可视化呈现EasyExcel只负责把结果数据高效地写进Excel或者从Excel高效地读出来。1.3 版本选择与环境预检我用的是目前生产环境验证过的组合组件版本说明SpringBoot2.7.x2.x系列稳定和EasyExcel兼容性好EasyExcel3.3.x3.x系列API更友好推荐使用POI5.2.xEasyExcel 3.x内部依赖POI 5.xJDK83.x版本要求JDK8及以上这里要注意一个版本坑EasyExcel 2.x和3.x的API差异很大网上的教程很多是2.x的老写法照搬会报方法不存在。我建议直接用3.xFastExcel工具类已经内置了大部分核心操作不需要写那么多样板代码。另外poi的版本不建议自己额外引入覆盖EasyExcel自带依赖管理强制覆盖版本容易引发莫名其妙的兼容问题。2. 基础工程搭建与核心依赖配置2.1 Maven依赖引入细节以SpringBoot项目为例在pom.xml里加入EasyExcel依赖。很多人直接复制下面这段就走dependency groupIdcom.alibaba/groupId artifactIdeasyexcel/artifactId version3.3.2/version /dependency这个写法在大多数情况下没问题但在实际项目里如果你们公司有自己的BOMBill of Materials统一管理第三方依赖版本注意不要和BOM里的POI版本冲突。我的做法是单独指定EasyExcel版本并且不额外引入poi-ooxml避免重复依赖。同时如果项目里用了hutool的Excel工具也要注意冲突。hutool的ExcelUtil底层是POI和EasyExcel共用POI类库时某些版本会产生NoSuchMethodError。我踩过一次后来把hutool的excel模块从依赖里排除了才解决。2.2 实体模型与注解配置导入导出第一个核心工作是把Excel列和Java实体字段做映射。EasyExcel提供了注解和无注解两种方式我强烈推荐注解方式代码可读性和维护性都更好。一个标准模型定义长这样Data public class OrderExcelModel { ExcelProperty(value 订单号, index 0) private String orderNo; ExcelProperty(value 下单时间, index 1) private Date orderTime; ExcelProperty(value 订单金额, index 2) private BigDecimal amount; ExcelProperty(value 收货人, index 3) private String receiverName; ExcelProperty(value 收货电话, index 4) private String receiverPhone; }index很好理解就是列索引从0开始。如果不指定indexEasyExcel会根据value名称去匹配表头这时表头名称和注解里的value必须完全一致包括空格。这里有几个细节值得注意Date类型字段默认导出格式是时间戳数字需要配合DateTimeFormat注解指定格式DateTimeFormat(yyyy-MM-dd HH:mm:ss) private Date orderTime;BigDecimal导出时默认会显示为科学计数法对Excel用户很不友好建议格式化NumberFormat(#.##) private BigDecimal amount;实体字段建议全部用包装类型别用基本类型。原因很简单导出时如果为null基本类型会输出默认值0容易误导报表使用者导入时Excel单元格为空转换基本类型也可能抛异常。2.3 通用工具类封装实际项目中导出导入绝不只一个模块用所以工具类是必须的。我封装了一个ExcelUtils把最常用的三个操作提炼成静态方法按模板导出、按自定义头导出、异步导入解析。public class ExcelUtils { public static T void writeExcel(HttpServletResponse response, String fileName, ClassT clazz, ListT dataList) throws IOException { setResponseHeader(response, fileName); EasyExcel.write(response.getOutputStream(), clazz) .sheet(数据) .doWrite(dataList); } public static T void writeExcelWithHead(HttpServletResponse response, String fileName, ListListString headList, ListListObject dataList) throws IOException { setResponseHeader(response, fileName); EasyExcel.write(response.getOutputStream()) .head(headList) .sheet(数据) .doWrite(dataList); } public static T void readExcel(MultipartFile file, ClassT clazz, AnalysisEventListenerT listener) throws IOException { EasyExcel.read(file.getInputStream(), clazz, listener) .sheet() .doRead(); } private static void setResponseHeader(HttpServletResponse response, String fileName) throws UnsupportedEncodingException { response.setContentType(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet); response.setCharacterEncoding(utf-8); String encodedFileName URLEncoder.encode(fileName, UTF-8).replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment;filename*utf-8 encodedFileName); } }里面的setResponseHeader特别关键很多新手直接写filename文件名.xlsx一旦文件名包含中文浏览器下载时就会出现乱码。这里用URLEncoder.encode做了编码转换并且采取filename*格式兼容大多数主流浏览器。3. 导出功能核心实现与性能优化3.1 大数据量导出分批写入与内存控制先看一个反面教材也是很多新手常犯的错误// 错误示例 ListOrderExcelModel allData orderMapper.selectAll(); // 一次性查50万条 EasyExcel.write(outputStream, OrderExcelModel.class).sheet().doWrite(allData);这段代码的问题在于selectAll()把50万条记录全加载到内存了即便EasyExcel写Excel再省内存你前面查出来的List本身就已经占了很大一块堆空间。数据量到达一定规模OOM几乎是必然的。正确做法是分批查询、分批写入public void exportLargeData(HttpServletResponse response) throws IOException { setResponseHeader(response, 订单明细导出); ExcelWriter excelWriter null; try { excelWriter EasyExcel.write(response.getOutputStream(), OrderExcelModel.class) .build(); WriteSheet writeSheet EasyExcel.writerSheet(订单明细).build(); // 分页查询每页1万条写一批释放一批 int pageSize 10000; int pageNum 1; ListOrderExcelModel pageData; do { pageData orderMapper.selectPage(pageNum, pageSize); if (CollectionUtils.isEmpty(pageData)) { break; } excelWriter.write(pageData, writeSheet); pageData.clear(); // 帮助GC回收 pageNum; } while (pageData.size() pageSize); } finally { if (excelWriter ! null) { excelWriter.finish(); } } }为什么这么写每次只从数据库取1万条占用的Java堆内存可控excelWriter.write(pageData, writeSheet)把内存中的数据转成Excel文件内容流式写到磁盘或网络流写完即可释放pageData.clear()主动把List引用置空让GC及时回收这里补充一个点ExcelWriter用完必须调用finish()否则会残留临时文件或者输出流不完整。我把finish()放在finally块里保证必定执行。3.2 动态列导出多Sheet与自定义表头固定实体类的导出只能处理列结构固定的表格现实业务里有大量场景需要动态生成表头。比如一个销售趋势报表列是1月、2月、3月...12月这个列集合是运行时根据条件生成的没法预先定义实体类。这时候就用到动态表头APIpublic void exportDynamicHead(HttpServletResponse response, ListString monthList, MapString, ListObject rowDataMap) throws IOException { setResponseHeader(response, 销售趋势报表); ListListString head new ArrayList(); // 第一列固定 head.add(Collections.singletonList(店铺名称)); // 动态月份列 for (String month : monthList) { head.add(Collections.singletonList(month 销售额)); } ListListObject rows new ArrayList(); for (Map.EntryString, ListObject entry : rowDataMap.entrySet()) { ListObject row new ArrayList(); row.add(entry.getKey()); row.addAll(entry.getValue()); rows.add(row); } EasyExcel.write(response.getOutputStream()) .head(head) .sheet(销售数据) .doWrite(rows); }注意动态表头模式下head是一个ListListString每个内层List代表一列。如果某列需要二级表头就在内层List里放多个字符串EasyExcel会自动合并单元格。比如head.add(Arrays.asList(2024年度, 第一季度));这会在表头显示2024年度合并单元格下挂第一季度。多级表头在生成复杂统计报表时非常实用。再说一个多Sheet场景。假设需要把12个月的数据分别写到12个Sheet里ExcelWriter excelWriter EasyExcel.write(response.getOutputStream(), OrderExcelModel.class).build(); for (int i 1; i 12; i) { String sheetName i 月; WriteSheet writeSheet EasyExcel.writerSheet(i - 1, sheetName).build(); ListOrderExcelModel monthData orderMapper.selectByMonth(i); excelWriter.write(monthData, writeSheet); } excelWriter.finish();这里有个容易踩的坑writerSheet的第一个参数是Sheet的序号从0开始不传序号的话重复同名Sheet会互相覆盖。3.3 导出时对字段进行自定义处理导出场景经常会遇到实体字段不能直接展示需要加工的情况。比如订单状态在数据库里是0/1/2报表里必须显示待支付/已支付/已取消再比如手机号中间四位要脱敏。有两种处理方式方式一在实体里增加一个临时展示字段用ExcelProperty注解标注业务层去填充ExcelProperty(value 订单状态, index 5) private String statusDesc;这种方式直观简单我大部分项目都是这样做的。缺点是实体类会多出不属于数据库表的冗余字段。方式二使用Converter转换器。定义一个枚举转换器public class OrderStatusConverter implements ConverterInteger { Override public Class? supportJavaTypeKey() { return Integer.class; } Override public CellDataTypeEnum supportExcelTypeKey() { return CellDataTypeEnum.STRING; } Override public Integer convertToJavaData(ReadConverterContext? context) { // 导入时Excel里的已支付转换为1 String statusStr context.getReadCellData().getStringValue(); return 已支付.equals(statusStr) ? 1 : 0; } Override public WriteCellData? convertToExcelData(WriteConverterContextInteger context) { // 导出时数字1转换为已支付 Integer status context.getValue(); String value status ! null status 1 ? 已支付 : 已取消; return new WriteCellData(value); } }然后在实体字段上标注ExcelProperty(value 订单状态, index 5, converter OrderStatusConverter.class) private Integer status;两种方案使用场景不同。如果只是导出时展示加工方式一更轻量如果同一个字段的导入导出都要加工方式二更优雅避免在多个业务层重复写if-else转换逻辑。3.4 导出时锁定表头与自适应列宽内存流式写入时用户拿到Excel第一反应是表头在哪。EasyExcel默认写出的表格没有冻结窗格数据量大时往下翻就看不到表头了。通过WriteSheet设置冻结窗格WriteSheet writeSheet EasyExcel.writerSheet(订单明细) .needHead(Boolean.TRUE) .build();但这只能控制是否输出表头行真正的冻结窗格需要依赖Sheet的createFreezePane。EasyExcel没有直接暴露这个API可以在afterAllHandlers里获取POI原生的Sheet对象设置WriteSheet writeSheet EasyExcel.writerSheet(订单明细) .registerWriteHandler(new AbstractRowWriteHandler() { Override public void afterSheetCreate(WriteWorkbookHolder writeWorkbookHolder, WriteSheetHolder writeSheetHolder) { org.apache.poi.ss.usermodel.Sheet sheet writeSheetHolder.getSheet(); // 冻结第一行 sheet.createFreezePane(0, 1); } }) .build();列宽方面EasyExcel默认列宽固定中文内容很容易显示不全。如果数据量不大几千行以内可以直接用Sheet设置列宽比如设置第0列宽20字符registerWriteHandler(new AbstractColumnWidthStyleStrategy() { Override protected void setColumnWidth(WriteSheetHolder writeSheetHolder, ListWriteCellData? cellDataList, Cell cell, Boolean isHead) { // 也可以按内容长度自动计算但注意大数据量下会拖慢速度 } });这里要提醒按内容长度自适应的列宽策略不要用在十万级以上的大数据量导出因为每次写一行都要遍历计算宽度性能会断崖式下降。大数据量场景要么固定列宽要么干脆不做自适应。4. 导入功能核心实现与防坑指南4.1 监听器机制与逐行处理原理导入比导出复杂的地方在于数据校验失败需要精确定位到行号、列号数据量大了不能一次性全部load进内存业务校验逻辑和文件解析逻辑要解耦。EasyExcel的导入核心是监听器。每个AnalysisEventListener维护自己的业务处理逻辑它逐行被回调而不是全部读完后一次性给你一个List。一个完整的导入监听器长这样Slf4j public class OrderImportListener extends AnalysisEventListenerOrderExcelModel { private static final int BATCH_SIZE 1000; private ListOrderExcelModel cache new ArrayList(); private final OrderService orderService; private final ImportResult result; public OrderImportListener(OrderService orderService, ImportResult result) { this.orderService orderService; this.result result; } Override public void invoke(OrderExcelModel data, AnalysisContext context) { // 逐行校验 Integer rowIndex context.readRowHolder().getRowIndex(); String errorMsg validate(data); if (StringUtils.isNotEmpty(errorMsg)) { result.addError(rowIndex, errorMsg); return; } cache.add(data); if (cache.size() BATCH_SIZE) { saveBatch(); } } Override public void doAfterAllAnalysed(AnalysisContext context) { // 剩余不足一批的数据也要入库 saveBatch(); log.info(本次导入完成成功{}条失败{}条, result.getSuccessCount(), result.getErrorCount()); } private void saveBatch() { orderService.batchSave(cache); result.increaseSuccess(cache.size()); cache.clear(); } private String validate(OrderExcelModel data) { if (StringUtils.isBlank(data.getOrderNo())) { return 订单号不能为空; } if (data.getAmount() null || data.getAmount().compareTo(BigDecimal.ZERO) 0) { return 订单金额必须大于0; } return null; } }这段代码的设计思路值得说一下逐行校验错误行直接记录到结果集不影响后续行解析满1000条批量入库减少数据库交互次数解析完成后把不满一批的也入库防止数据丢失导入结果用独立的ImportResult对象收集不污染业务逻辑4.2 导入模板下载与校验机制匹配导入功能必须配套提供一个模板下载功能。用户先下载模板按模板格式填充数据后再上传这样能大幅降低导入报错率。模板下载本质上就是一次空的导出GetMapping(/template) public void template(HttpServletResponse response) throws IOException { setResponseHeader(response, 订单导入模板); ListOrderExcelModel emptyList Collections.emptyList(); EasyExcel.write(response.getOutputStream(), OrderExcelModel.class) .sheet(订单导入) .needHead(Boolean.TRUE) .doWrite(emptyList); }模板里只含表头不包含任何数据行。另外我建议在模板里加一个示例数据行并隐藏掉这样既能引导用户填写格式又不会影响解析需要解析时跳过第一行数据。不过隐藏行容易让用户困惑实践下来效果一般我这里顺便提一句作为参考。还有一点很关键校验逻辑必须和模板的表头完全一致。比如模板里没有订单状态这一列但实体类里status字段加了ExcelProperty(value 订单状态)导入时就会报找到不匹配的头或者干脆所有行都读不出status值。建议导入前先做一次表头校验看Excel模板列头是否符合预期。表头校验可以这样实现public void checkHead(MultipartFile file, ListString expectHead) { try (InputStream inputStream file.getInputStream()) { ExcelReader excelReader EasyExcel.read(inputStream).build(); ReadSheet readSheet EasyExcel.readSheet(0).build(); // 只读取表头 excelReader.read(readSheet); ListString actualHead ... // 通过listener获取第一行 } }业界更常见的做法是直接复用导入监听器在invokeHeadMap回调里拿到表头Map做比对。EasyExcel的AnalysisEventListener里有一个invokeHeadMap(MapInteger, String headMap, AnalysisContext context)方法重写它就能在解析正文之前先校验表头。4.3 大文件导入的IO流处理细节用户上传的Excel文件可能是几十MB的大文件。直接file.getInputStream()没问题但要注意生产环境不敢把最大上传体积调太高一般spring.servlet.multipart.max-file-size设10MB或20MB实际项目中有压缩包上传的场景解压后再解析注意解压后的临时文件要按时间清理导入时建议对文件流做try-with-resources防止流泄漏贴近实战的完整导入接口长这样PostMapping(/import) public R importExcel(RequestParam(file) MultipartFile file) throws IOException { if (file null || file.isEmpty()) { return R.fail(上传文件不能为空); } // 校验文件格式 String fileName file.getOriginalFilename(); if (!fileName.endsWith(.xlsx) !fileName.endsWith(.xls)) { return R.fail(仅支持.xlsx或.xls格式的Excel文件); } ImportResult result new ImportResult(); OrderImportListener listener new OrderImportListener(orderService, result); try (InputStream inputStream file.getInputStream()) { EasyExcel.read(inputStream, OrderExcelModel.class, listener) .sheet() .headRowNumber(1) // 表头占1行正文从第2行开始 .doRead(); } catch (Exception e) { log.error(文件解析异常, e); return R.fail(文件解析失败 e.getMessage()); } return R.ok(result); }这里面headRowNumber(1)的含义一定要理解。如果模板第一行是标题比如订单导入模板第二行才是表头那就要设headRowNumber(2)否则解析会把表头当成数据。4.4 导入数据一致性保障导入不是读出来然后一条条insert这么简单生产环境要保障数据一致性。我的实践是在doAfterAllAnalysed之后再对校验通过的数据做事务性入库处理。具体做法是在业务方法上开启事务Transactional(rollbackFor Exception.class) public void batchSave(ListOrderExcelModel list) { // 批量插入或更新 }但这有个问题上面监听器的saveBatch会分批调用batchSave如果最后一批出了异常前面几批已经提交的数据就不会回滚。针对这个情况有两种方案方案一全量校验通过后再统一入库。先把所有数据读到一个List里然后整体交给事务方法处理。缺点是数据量大时占用内存多和导入的初衷相悖。方案二分批入库并记录批次状态。哪一批失败就重试哪一批错误信息精确到批次。适合导入数据本身互相独立、允许部分成功的场景。实际业务中我常用方案一的小数据量版本限制单次导入文件行数比如最多5000行保证所有数据能一次性加载到内存然后整体事务提交出了任何一条脏数据全部回滚用户重新修改后再导入。这种模式对业务一致性要求高的场景比如财务账目导入是最稳妥的。5. Excel导入导出的性能调优实战5.1 百万数据导出的JVM参数与GC调优生产环境跑大数据量导出JVM参数设置很关键。以导出100万行、每行30列左右的报表为例我的经验参数如下-Xms2048m -Xmx4096m -XX:UseG1GC -XX:MaxGCPauseMillis200简单解释一下EasyExcel是流式写出堆内存占用相对可控4GB足够应对百万级导出G1垃圾回收器相比CMS更适合这种大对象持续产生-短期存活的场景停顿时间更稳定MaxGCPauseMillis200限制GC最大停顿避免导出过程中接口响应时间出现长尾如果服务本身堆内存无法给到4GB那就得从代码层面继续优化把导出逻辑扔到MQ里异步处理生成文件后上传到对象存储再给用户一个下载链接。这是另一个维度的话题但实际项目中非常常见。5.2 导入速度优化批量插入与并行解析导入性能的瓶颈通常在数据库写入而不是文件解析。EasyExcel解析一个10万行的xlsx文件纯解析也就几秒但如果你一条一条insert10万条数据可能要跑二十几分钟。批量插入是标配优化手段Transactional public void batchSave(ListOrderExcelModel list) { // 用MyBatis的foreach批量插入分批1000条执行一次 orderMapper.batchInsert(list); }insert idbatchInsert parameterTypelist insert into t_order (order_no, order_time, amount, receiver_name, receiver_phone) values foreach collectionlist itemitem separator, (#{item.orderNo}, #{item.orderTime}, #{item.amount}, #{item.receiverName}, #{item.receiverPhone}) /foreach /insert注意MyBatis的foreach拼接SQL有长度限制一次1000条比较安全5000条以上容易触发数据库max_allowed_packet超限。数据库层面也有优化空间比如导入时可以临时关闭唯一索引检查导完再开启。但生产环境不要这么做容易造成索引不一致风险大于收益。更稳妥的作法是直接用INSERT IGNORE或者ON DUPLICATE KEY UPDATE来做去重写入但注意这只适用于MySQL场景。另一种导入优化思路是并行解析。EasyExcel官方不推荐多线程读同一个Sheet因为Sheet内部解析是有状态的。但多个文件可以并行解析ExecutorService executorService Executors.newFixedThreadPool(4); for (MultipartFile file : files) { executorService.submit(() - { ImportResult result new ImportResult(); try (InputStream inputStream file.getInputStream()) { EasyExcel.read(inputStream, OrderExcelModel.class, new OrderImportListener(orderService, result)) .sheet() .doRead(); } return result; }); }这种方式适合一次上传多个Excel文件的场景例如按分店批量上传注意线程池大小不要超过CPU核数否则频繁上下文切换反而变慢。5.3 内存对比实测POI与EasyExcel的差异我早前在一台4核8G的测试机上做过一次对比实验导出30万行、25列数据方案堆内存峰值耗时是否OOMPOI XSSFWorkbook2.4GB38秒否接近临界POI SXSSFWorkbook900MB22秒否EasyExcel320MB18秒否这个数据不完全科学因为机器状态、JVM参数不同都会影响结果但趋势是明确的EasyExcel的内存占用约为POI XSSF的1/7速度反而更快。又测了导入场景EasyExcel读一个10万行xlsx文件堆内存峰值大概160MBPOI XSSF读同样文件至少要1.2GB差距悬殊。这也是为什么在线导入功能在大数据量场景下几乎只能选择EasyExcel类方案的原因。6. 实践中的常见问题与排查经验6.1 中文文件名下载乱码问题这个问题几乎每个项目都会遇到而且排查起来很容易忽略。浏览器下载文件时对Content-Disposition头的解析规则很挑剔早期的写法response.setHeader(Content-Disposition, attachment; filename fileName);只要文件名是中文Chrome和Firefox大概率乱码。是因为这个Header只能包含ASCII字符中文未经编码直接放进去就会出问题。正确做法已经在上文工具类里写过了再重复强调一次String encodedFileName URLEncoder.encode(fileName, UTF-8).replaceAll(\\, %20); response.setHeader(Content-Disposition, attachment;filename*utf-8 encodedFileName);两个要点URLEncoder.encode会把空格变成而Header里会被解析为空格所以必须replaceAll(\\, %20)转回空格编码filename*是RFC 5987规范格式为utf-8编码后的文件名前后都不能错6.2 Date类型与Excel单元格格式的时区偏差导出的时间字段用户反馈和数据库里的时间差了8小时。排查后发现是POI底层处理Date类型时读取了本地时区。测试环境和服务器时区不一致导致导出Excel中看到的日期时间有偏差。解决方案有两个一是实体字段统一用字符串时间ExcelProperty(value 下单时间, index 1) private String orderTimeStr; // 业务层格式化好再放进来二是设置全局时区TimeZone.setDefault(TimeZone.getTimeZone(Asia/Shanghai));我建议生产环境直接用方案一因为方案二会全局影响JVM所有时间处理逻辑可能引发其他问题属于解决一个问题引入另一个问题。6.3 导入时空行与空白Sheet的兜底处理用户上传的Excel经常有莫名其妙的空行尤其从某个系统导出的文件末尾可能带几十个空行。如果监听器不做处理空行也会触发invoke回调虽然实体类字段全部为null但依然会走一遍校验逻辑产生一堆无意义的错误记录。兜底处理很关键在invoke方法头部拦截Override public void invoke(OrderExcelModel data, AnalysisContext context) { if (data null || isAllFieldNull(data)) { return; } // 正常业务逻辑 } private boolean isAllFieldNull(OrderExcelModel data) { return StringUtils.isAllBlank(data.getOrderNo(), data.getReceiverName()) data.getAmount() null data.getOrderTime() null; }注意isAllBlank是Hutool的方法如果项目没引Hutool就手动判断各个字段。这里还有个细节HTTP请求里上传的IE浏览器版本很低时MultipartFile的原始文件名获取会有差异IE全家桶对filename和filename*的支持很烂如果你们的系统还需要兼容老旧浏览器建议前端先做一次文件名校验再上传。6.4 并发导出的连接池与线程池配置报表导出功能通常也是高并发入口多个用户同时点导出后端如果处理不当很容易打垮数据库。我的建议导出接口使用异步线程池前端轮询下载状态文件生成好再提示下载限制导出接口的并发数用信号量控制同时导出任务不超过3~5个数据库连接池HikariCP的maximum-pool-size要结合导出占用连接计算。一个批量查询导出会占用一个数据库连接很长时间如果连接池只有10个连接5个用户在导出剩下5个连接要支撑所有其他业务请求极易连接池耗尽通过Semaphore做并发控制的简单示例private final Semaphore exportSemaphore new Semaphore(3); public void export(HttpServletResponse response, ExportQuery query) throws IOException { if (!exportSemaphore.tryAcquire()) { throw new BusinessException(当前导出任务过多请稍后再试); } try { doExport(response, query); } finally { exportSemaphore.release(); } }这个示例是同步导出的做法更友好的体验是异步导出然后推送下载链接核心思路是一样的限制并发数量保护下游资源。6.5 问题速查表现象可能原因解决方案导出Excel打不开提示损坏输出流没有调用finish()确保finally中调用excelWriter.finish()中文表头变乱码Content-Disposition头编码问题使用filename*并URL编码导入时时间少了8小时JVM默认时区和预期不一致使用字符串时间字段或显式设置时区导入只有表头没有数据headRowNumber设置不对检查模板前几行调整headRowNumber大批量导出内存飙升一次性查询全量数据到内存分页查询分批写入导入时实体字段全部为nullExcel列索引和实体index不匹配检查模板表头顺序和ExcelProperty的index对齐首行数据被当成表头模板第一行是标题行headRowNumber(2)7. 实际项目应用的经验总结最后分享几个我在这类项目里沉淀下来的实操经验不是理论推断是真实踩坑换来的。第一个关于项目架构不要把导入导出逻辑塞在Controller里。我最初图省事直接在Controller写了个两三百行的方法后来需求一改就痛苦。现在我的做法是抽出一个独立的ReportService层Controller只负责接收参数和返回结果文件处理、数据校验、业务落库全在Service层管理。这样单个导出导入方法能控制在让后继者看懂的范围里。第二个关于日志导入导出场景必须打日志而且要打印行号和错误原因。用户反馈我上传的文件导不进去如果没有日志排查全靠猜。我在监听器里每个出错行都会log.warn(第{}行导入失败{}, rowIndex, errorMsg)运维出问题一查日志立刻定位。第三个关于产品设计导入前坚持让用户下载模板。很多开发觉得下载模板多此一举实际上模板能规范用户上传格式从源头减少脏数据。模板里我也加了示例行和必填标记红色字体用户的首次成功率非常高。第四个关于测试做导入功能测试用例一定要包含空文件、只有表头、100MB大文件、带空行、带特殊字符、带公式单元格这些边界场景。尤其带公式单元格的场景容易被忽略Excel里某个单元格内容是SUM(A1:A10)直接用EasyExcel读出来拿到的是公式字符串而不是计算结果如果你的业务期望拿值需要在Excel模板上做配合或者接受这个行为。做这类功能不追求代码花哨重点是逻辑严谨、内存可控、边界场景都兜住。这套整合方案我在多个项目上用过导出百万级数据稳定不OOM导入十万级数据校验入库控制在十几秒内生产环境用了两三年没出过大问题。照着这篇文章的思路走你的报表模块也能少走不少弯路。
