企业官网建设流程全解析

报表导出导入这个需求，几乎每个后台管理系统都躲不掉。早些年我用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 版本选择与环境预检

我用的是目前生产环境验证过的组合：

这里要注意一个版本坑：EasyExcel 2.x和3.x的API差异很大，网上的教程很多是2.x的老写法，照搬会报方法不存在。我建议直接用3.x，FastExcel工具类已经内置了大部分核心操作，不需要写那么多样板代码。另外poi的版本不建议自己额外引入覆盖，EasyExcel自带依赖管理，强制覆盖版本容易引发莫名其妙的兼容问题。

2. 基础工程搭建与核心依赖配置

2.1 Maven依赖引入细节

以SpringBoot项目为例，在pom.xml里加入EasyExcel依赖。很多人直接复制下面这段就走：

<dependency> <groupId>com.alibaba</groupId> <artifactId>easyexcel</artifactId> <version>3.3.2</version> </dependency>

这个写法在大多数情况下没问题，但在实际项目里，如果你们公司有自己的BOM（Bill 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开始。如果不指定index，EasyExcel会根据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, Class<T> clazz, List<T> dataList) throws IOException { setResponseHeader(response, fileName); EasyExcel.write(response.getOutputStream(), clazz) .sheet("数据") .doWrite(dataList); } public static <T> void writeExcelWithHead(HttpServletResponse response, String fileName, List<List<String>> headList, List<List<Object>> dataList) throws IOException { setResponseHeader(response, fileName); EasyExcel.write(response.getOutputStream()) .head(headList) .sheet("数据") .doWrite(dataList); } public static <T> void readExcel(MultipartFile file, Class<T> clazz, AnalysisEventListener<T> 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 大数据量导出：分批写入与内存控制

先看一个反面教材，也是很多新手常犯的错误：

// 错误示例 List<OrderExcelModel> 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; List<OrderExcelModel> 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月"，这个列集合是运行时根据条件生成的，没法预先定义实体类。

这时候就用到动态表头API：

public void exportDynamicHead(HttpServletResponse response, List<String> monthList, Map<String, List<Object>> rowDataMap) throws IOException { setResponseHeader(response, "销售趋势报表"); List<List<String>> head = new ArrayList<>(); // 第一列固定 head.add(Collections.singletonList("店铺名称")); // 动态月份列 for (String month : monthList) { head.add(Collections.singletonList(month + "销售额")); } List<List<Object>> rows = new ArrayList<>(); for (Map.Entry<String, List<Object>> entry : rowDataMap.entrySet()) { List<Object> row = new ArrayList<>(); row.add(entry.getKey()); row.addAll(entry.getValue()); rows.add(row); } EasyExcel.write(response.getOutputStream()) .head(head) .sheet("销售数据") .doWrite(rows); }

注意动态表头模式下，head是一个List<List<String>>，每个内层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(); List<OrderExcelModel> 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 Converter<Integer> { @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(WriteConverterContext<Integer> 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, List<WriteCellData<?>> cellDataList, Cell cell, Boolean isHead) { // 也可以按内容长度自动计算，但注意大数据量下会拖慢速度 } });

这里要提醒：按内容长度自适应的列宽策略不要用在十万级以上的大数据量导出，因为每次写一行都要遍历计算宽度，性能会断崖式下降。大数据量场景要么固定列宽，要么干脆不做自适应。

4. 导入功能核心实现与防坑指南

4.1 监听器机制与逐行处理原理

导入比导出复杂的地方在于：数据校验失败需要精确定位到行号、列号；数据量大了不能一次性全部load进内存；业务校验逻辑和文件解析逻辑要解耦。

EasyExcel的导入核心是监听器。每个AnalysisEventListener维护自己的业务处理逻辑，它逐行被回调，而不是全部读完后一次性给你一个List。

一个完整的导入监听器长这样：

@Slf4j public class OrderImportListener extends AnalysisEventListener<OrderExcelModel> { private static final int BATCH_SIZE = 1000; private List<OrderExcelModel> 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, "订单导入模板"); List<OrderExcelModel> 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, List<String> expectHead) { try (InputStream inputStream = file.getInputStream()) { ExcelReader excelReader = EasyExcel.read(inputStream).build(); ReadSheet readSheet = EasyExcel.readSheet(0).build(); // 只读取表头 excelReader.read(readSheet); List<String> actualHead = ... // 通过listener获取第一行 } }

业界更常见的做法是直接复用导入监听器，在invokeHeadMap回调里拿到表头Map做比对。EasyExcel的AnalysisEventListener里有一个invokeHeadMap(Map<Integer, 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(List<OrderExcelModel> list) { // 批量插入或更新 }

但这有个问题：上面监听器的saveBatch会分批调用batchSave，如果最后一批出了异常，前面几批已经提交的数据就不会回滚。

针对这个情况，有两种方案：

方案一，全量校验通过后再统一入库。先把所有数据读到一个List里，然后整体交给事务方法处理。缺点是数据量大时占用内存多，和导入的初衷相悖。

方案二，分批入库并记录批次状态。哪一批失败就重试哪一批，错误信息精确到批次。适合导入数据本身互相独立、允许部分成功的场景。

实际业务中我常用方案一的小数据量版本：限制单次导入文件行数（比如最多5000行），保证所有数据能一次性加载到内存，然后整体事务提交，出了任何一条脏数据全部回滚，用户重新修改后再导入。这种模式对业务一致性要求高的场景（比如财务账目导入）是最稳妥的。

5. Excel导入导出的性能调优实战

5.1 百万数据导出的JVM参数与GC调优

生产环境跑大数据量导出，JVM参数设置很关键。以导出100万行、每行30列左右的报表为例，我的经验参数如下：

-Xms2048m -Xmx4096m -XX:+UseG1GC -XX:MaxGCPauseMillis=200

简单解释一下：

• EasyExcel是流式写出，堆内存占用相对可控，4GB足够应对百万级导出
• G1垃圾回收器相比CMS更适合这种"大对象持续产生-短期存活"的场景，停顿时间更稳定
• MaxGCPauseMillis=200限制GC最大停顿，避免导出过程中接口响应时间出现长尾

如果服务本身堆内存无法给到4GB，那就得从代码层面继续优化：把导出逻辑扔到MQ里异步处理，生成文件后上传到对象存储，再给用户一个下载链接。这是另一个维度的话题，但实际项目中非常常见。

5.2 导入速度优化：批量插入与并行解析

导入性能的瓶颈通常在数据库写入，而不是文件解析。EasyExcel解析一个10万行的xlsx文件，纯解析也就几秒，但如果你一条一条insert，10万条数据可能要跑二十几分钟。

批量插入是标配优化手段：

@Transactional public void batchSave(List<OrderExcelModel> list) { // 用MyBatis的foreach批量插入，分批1000条执行一次 orderMapper.batchInsert(list); }

<insert id="batchInsert" parameterType="list"> insert into t_order (order_no, order_time, amount, receiver_name, receiver_phone) values <foreach collection="list" item="item" 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列数据：

这个数据不完全科学，因为机器状态、JVM参数不同都会影响结果，但趋势是明确的：EasyExcel的内存占用约为POI XSSF的1/7，速度反而更快。

又测了导入场景，EasyExcel读一个10万行xlsx文件，堆内存峰值大概160MB，POI 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 问题速查表

7. 实际项目应用的经验总结

最后分享几个我在这类项目里沉淀下来的实操经验，不是理论推断，是真实踩坑换来的。

第一个关于项目架构：不要把导入导出逻辑塞在Controller里。我最初图省事直接在Controller写了个两三百行的方法，后来需求一改就痛苦。现在我的做法是抽出一个独立的ReportService层，Controller只负责接收参数和返回结果，文件处理、数据校验、业务落库全在Service层管理。这样单个导出导入方法能控制在让后继者看懂的范围里。

第二个关于日志：导入导出场景必须打日志，而且要打印行号和错误原因。用户反馈"我上传的文件导不进去"，如果没有日志，排查全靠猜。我在监听器里每个出错行都会log.warn("第{}行导入失败：{}", rowIndex, errorMsg)，运维出问题一查日志立刻定位。

第三个关于产品设计：导入前坚持让用户下载模板。很多开发觉得下载模板多此一举，实际上模板能规范用户上传格式，从源头减少脏数据。模板里我也加了示例行和必填标记（红色字体），用户的首次成功率非常高。

第四个关于测试：做导入功能，测试用例一定要包含空文件、只有表头、100MB大文件、带空行、带特殊字符、带公式单元格这些边界场景。尤其带公式单元格的场景容易被忽略，Excel里某个单元格内容是=SUM(A1:A10)，直接用EasyExcel读出来拿到的是公式字符串而不是计算结果，如果你的业务期望拿值，需要在Excel模板上做配合或者接受这个行为。

做这类功能，不追求代码花哨，重点是逻辑严谨、内存可控、边界场景都兜住。这套整合方案我在多个项目上用过，导出百万级数据稳定不OOM，导入十万级数据校验入库控制在十几秒内，生产环境用了两三年没出过大问题。照着这篇文章的思路走，你的报表模块也能少走不少弯路。