SpringBoot项目实战：3分钟搞定EasyExcel文件流导出（含完整代码）

SpringBoot实战：用EasyExcel实现高效文件流导出的深度指南

最近在几个企业级项目中，我频繁遇到需要处理大批量数据导出的场景。传统的POI库在处理上万行数据时，内存占用和性能问题逐渐凸显，而阿里开源的EasyExcel则以其卓越的内存优化和简洁的API设计，成为了我们团队的首选方案。但真正将EasyExcel集成到生产环境，特别是处理文件流导出时，我发现很多开发者容易在响应头设置、编码处理、资源管理这些细节上栽跟头。今天，我就结合自己踩过的坑和积累的最佳实践，分享一套完整的SpringBoot集成EasyExcel文件流导出方案。

这篇文章面向的是已经具备SpringBoot基础，但在实际项目中需要快速、稳定实现Excel导出功能的开发者。我会从环境配置开始，逐步深入到高级特性，每个环节都提供可直接复用的代码，并解释背后的原理和注意事项。无论你是要处理简单的数据报表，还是需要应对百万级数据的导出需求，这套方案都能为你提供清晰的实现路径。

1. 环境准备与基础配置

1.1 依赖引入与版本选择

在SpringBoot项目中集成EasyExcel，第一步自然是添加依赖。但版本选择往往被忽视，实际上不同版本在API稳定性和功能支持上存在差异。我推荐使用当前主流的稳定版本，同时注意与SpringBoot版本的兼容性。

<!-- pom.xml中的依赖配置 --> <dependency> <groupId>com.alibaba</groupId> <artifactId>easyexcel</artifactId> <version>3.3.2</version> </dependency>

注意：EasyExcel 3.x版本相比2.x在API设计上更加规范，修复了多个已知的内存泄漏问题。如果你的项目还在使用2.x版本，建议评估升级的必要性，特别是当导出数据量较大时。

除了核心依赖，我通常还会添加一些辅助工具，让开发体验更顺畅：

<dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> </dependency>

Lombok可以简化实体类的编写，而Validation则能在数据导出前进行必要的校验。这些虽然不是EasyExcel的强制依赖，但在实际项目中能显著提升代码质量。

1.2 基础实体类设计

EasyExcel通过注解驱动的方式定义Excel的结构，这种设计既灵活又直观。下面是一个用户信息导出的完整示例：

@Data @HeadRowHeight(20) // 设置表头行高 @ContentRowHeight(15) // 设置内容行高 public class UserExportModel { @ExcelProperty(value = "用户ID", index = 0) @ColumnWidth(10) private Long userId; @ExcelProperty(value = "用户名", index = 1) @ColumnWidth(20) private String username; @ExcelProperty(value = "邮箱地址", index = 2) @ColumnWidth(25) private String email; @ExcelProperty(value = "注册时间", index = 3) @ColumnWidth(18) @DateTimeFormat("yyyy-MM-dd HH:mm:ss") private Date registerTime; @ExcelProperty(value = "账户状态", index = 4) @ColumnWidth(12) private String status; @ExcelProperty(value = "账户余额", index = 5) @ColumnWidth(15) @NumberFormat("#,##0.00") private BigDecimal balance; }

这里有几个关键点需要特别注意：

• @ExcelProperty：这是最核心的注解，value定义列标题，index定义列顺序（从0开始）
• @ColumnWidth：设置列宽，单位是字符数。如果不设置，EasyExcel会自动调整，但有时会导致列宽不合适
• 格式化注解：@DateTimeFormat和@NumberFormat让数据展示更加友好
• 行高设置：通过类级别的@HeadRowHeight和@ContentRowHeight可以统一控制行高

在实际项目中，我建议为不同的导出场景创建专门的Model类，而不是复用业务实体。这样既能保持导出结构的稳定性，又能避免业务变更对导出功能的影响。

2. 核心导出实现与响应处理

2.1 控制器层的最佳实践

控制器层的实现看似简单，但细节决定成败。一个健壮的导出接口需要处理好编码、文件名、响应类型等多个方面。下面是我在实际项目中验证过的完整实现：

@RestController @RequestMapping("/api/export") @Slf4j public class ExportController { @GetMapping("/users") public void exportUsers( HttpServletResponse response, @RequestParam(required = false, defaultValue = "用户列表") String fileName, @RequestParam(required = false) String startDate, @RequestParam(required = false) String endDate) { try { // 1. 设置响应头 - 这是最关键的一步 setResponseHeaders(response, fileName); // 2. 获取输出流 ServletOutputStream outputStream = response.getOutputStream(); // 3. 构建查询条件并获取数据 List<UserExportModel> dataList = buildExportData(startDate, endDate); // 4. 执行导出 EasyExcel.write(outputStream, UserExportModel.class) .autoCloseStream(true) // 自动关闭流，避免资源泄漏 .sheet("用户信息") // 设置工作表名称 .doWrite(dataList); log.info("用户数据导出成功，文件名：{}，数据量：{}", fileName, dataList.size()); } catch (IOException e) { log.error("导出过程发生IO异常", e); throw new RuntimeException("导出失败，请稍后重试"); } catch (Exception e) { log.error("导出过程发生未知异常", e); throw new RuntimeException("系统异常，导出失败"); } } /** * 设置响应头，处理中文文件名和编码问题 */ private void setResponseHeaders(HttpServletResponse response, String fileName) throws UnsupportedEncodingException { // 清理响应头，避免缓存问题 response.reset(); // 设置内容类型 response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); // 设置字符编码 response.setCharacterEncoding("UTF-8"); // 处理中文文件名 - 兼容各种浏览器 String encodedFileName = URLEncoder.encode(fileName, "UTF-8") .replaceAll("\\+", "%20"); // 设置Content-Disposition，使用RFC 5987标准 String contentDisposition = String.format( "attachment; filename=\"%s.xlsx\"; filename*=UTF-8''%s.xlsx", encodedFileName, encodedFileName); response.setHeader("Content-Disposition", contentDisposition); // 禁用缓存，确保每次都能获取最新文件 response.setHeader("Cache-Control", "no-cache, no-store, must-revalidate"); response.setHeader("Pragma", "no-cache"); response.setHeader("Expires", "0"); } /** * 构建导出数据 - 实际项目中这里会调用Service层 */ private List<UserExportModel> buildExportData(String startDate, String endDate) { // 模拟数据，实际项目中从数据库查询 List<UserExportModel> list = new ArrayList<>(); for (int i = 1; i <= 100; i++) { UserExportModel user = new UserExportModel(); user.setUserId((long) i); user.setUsername("用户" + i); user.setEmail("user" + i + "@example.com"); user.setRegisterTime(new Date()); user.setStatus(i % 2 == 0 ? "正常" : "冻结"); user.setBalance(new BigDecimal(i * 1000.50)); list.add(user); } return list; } }

这个实现中有几个技术要点需要特别关注：

响应头设置的细节处理

文件名编码问题是最常见的坑。我使用了RFC 5987标准的方式，这种方式能更好地兼容各种浏览器：

// 传统方式（有兼容性问题） response.setHeader("Content-Disposition", "attachment;filename=" + URLEncoder.encode(fileName, "UTF-8")); // 推荐方式（RFC 5987标准） String contentDisposition = String.format( "attachment; filename=\"%s.xlsx\"; filename*=UTF-8''%s.xlsx", encodedFileName, encodedFileName);

资源管理的最佳实践

EasyExcel的autoCloseStream(true)参数非常重要，它能确保输出流被正确关闭，避免资源泄漏。但即使有这个参数，我们也要在异常处理中做好清理工作。

异常处理的完整性

导出操作涉及IO、数据库、业务逻辑等多个环节，任何一个环节出错都可能导致导出失败。完整的异常处理不仅能提供更好的用户体验，还能帮助快速定位问题。

2.2 响应头设置的深度解析

很多开发者在设置响应头时只关注Content-Disposition，实际上完整的响应头设置需要考虑多个方面。下面是一个响应头设置的对比表格，展示了不同设置的优劣：

在实际项目中，我还会根据具体需求添加一些额外的响应头：

// 对于大文件导出，可以启用分块传输 response.setHeader("Accept-Ranges", "bytes"); // 设置文件大小（如果能够提前计算） // response.setHeader("Content-Length", String.valueOf(fileSize)); // 对于敏感数据，可以添加安全相关的响应头 response.setHeader("X-Content-Type-Options", "nosniff");

3. 高级特性与性能优化

3.1 大数据量分页导出

当数据量达到数十万甚至百万级别时，一次性加载所有数据到内存显然不现实。EasyExcel提供了两种处理大数据量的方式：分页查询和流式写入。

方案一：分页查询 + 分批写入

public void exportLargeData(HttpServletResponse response, String fileName) throws IOException { setResponseHeaders(response, fileName); ServletOutputStream outputStream = response.getOutputStream(); // 创建ExcelWriter ExcelWriter excelWriter = EasyExcel.write(outputStream, UserExportModel.class) .autoCloseStream(false) // 手动管理流 .build(); WriteSheet writeSheet = EasyExcel.writerSheet("大数据导出").build(); int pageSize = 5000; // 每页大小 int pageNum = 1; boolean hasNext = true; try { while (hasNext) { // 分页查询数据 List<UserExportModel> pageData = userService.getUsersByPage(pageNum, pageSize); if (pageData.isEmpty()) { hasNext = false; } else { // 写入当前页数据 excelWriter.write(pageData, writeSheet); pageNum++; // 每写入5页刷新一次，平衡性能和内存 if (pageNum % 5 == 0) { outputStream.flush(); } } } excelWriter.finish(); outputStream.flush(); } finally { // 确保资源被释放 if (excelWriter != null) { excelWriter.finish(); } outputStream.close(); } }

方案二：数据库游标 + 流式处理

对于超大数据集，我更喜欢使用数据库游标的方式：

@Transactional(readOnly = true) public void exportWithCursor(HttpServletResponse response, String fileName) { setResponseHeaders(response, fileName); try (ServletOutputStream outputStream = response.getOutputStream(); // 使用try-with-resources确保资源释放 ExcelWriter excelWriter = EasyExcel.write(outputStream, UserExportModel.class) .autoCloseStream(false) .build()) { WriteSheet writeSheet = EasyExcel.writerSheet("流式导出").build(); // 使用游标逐行处理 try (Cursor<User> cursor = userRepository.findAllWithCursor()) { while (cursor.hasNext()) { User user = cursor.next(); UserExportModel model = convertToExportModel(user); // 单行写入 excelWriter.write(Collections.singletonList(model), writeSheet); // 每1000行刷新一次 if (cursor.getPosition() % 1000 == 0) { outputStream.flush(); } } } } catch (Exception e) { log.error("流式导出失败", e); throw new RuntimeException("导出过程中发生错误"); } }

两种方案的对比：

3.2 样式自定义与模板导出

EasyExcel提供了丰富的样式自定义能力。下面是一个设置复杂样式的示例：

public void exportWithCustomStyle(HttpServletResponse response) throws IOException { setResponseHeaders(response, "带样式报表"); ServletOutputStream outputStream = response.getOutputStream(); // 定义表头样式 WriteCellStyle headStyle = new WriteCellStyle(); headStyle.setFillForegroundColor(IndexedColors.GREY_25_PERCENT.getIndex()); headStyle.setFillPatternType(FillPatternType.SOLID_FOREGROUND); headStyle.setHorizontalAlignment(HorizontalAlignment.CENTER); // 定义内容样式 WriteCellStyle contentStyle = new WriteCellStyle(); contentStyle.setHorizontalAlignment(HorizontalAlignment.LEFT); contentStyle.setVerticalAlignment(VerticalAlignment.CENTER); // 设置边框 WriteCellStyle borderStyle = new WriteCellStyle(); borderStyle.setBorderLeft(BorderStyle.THIN); borderStyle.setBorderRight(BorderStyle.THIN); borderStyle.setBorderTop(BorderStyle.THIN); borderStyle.setBorderBottom(BorderStyle.THIN); // 合并样式 headStyle.cloneStyle(borderStyle); contentStyle.cloneStyle(borderStyle); // 创建写入器并应用样式 EasyExcel.write(outputStream, UserExportModel.class) .registerWriteHandler(new HorizontalCellStyleStrategy(headStyle, contentStyle)) .registerWriteHandler(new LongestMatchColumnWidthStyleStrategy()) // 自动列宽 .sheet("样式报表") .doWrite(getExportData()); }

对于更复杂的报表，可以使用模板导出：

public void exportWithTemplate(HttpServletResponse response) throws IOException { setResponseHeaders(response, "模板报表"); // 加载模板文件 InputStream templateStream = getClass().getResourceAsStream("/templates/report_template.xlsx"); ServletOutputStream outputStream = response.getOutputStream(); EasyExcel.write(outputStream) .withTemplate(templateStream) .sheet() .doFill(getReportData()); templateStream.close(); }

4. 生产环境的最佳实践

4.1 异常处理与监控

在生产环境中，导出功能需要有完善的异常处理和监控机制。我通常会在以下几个方面加强：

统一的异常处理

@ControllerAdvice @Slf4j public class ExportExceptionHandler { @ExceptionHandler(IOException.class) @ResponseBody public ResponseEntity<ErrorResponse> handleIOException(IOException e) { log.error("导出IO异常", e); return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR) .body(new ErrorResponse("FILE_EXPORT_ERROR", "文件导出失败，请稍后重试")); } @ExceptionHandler(DataAccessException.class) @ResponseBody public ResponseEntity<ErrorResponse> handleDataAccessException(DataAccessException e) { log.error("导出数据访问异常", e); return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR) .body(new ErrorResponse("DATA_ACCESS_ERROR", "数据查询失败")); } // 更多异常处理... } @Data @AllArgsConstructor class ErrorResponse { private String code; private String message; private long timestamp = System.currentTimeMillis(); }

性能监控与日志

@Aspect @Component @Slf4j public class ExportMonitorAspect { @Around("@annotation(ExportOperation)") public Object monitorExport(ProceedingJoinPoint joinPoint) throws Throwable { String methodName = joinPoint.getSignature().getName(); long startTime = System.currentTimeMillis(); try { Object result = joinPoint.proceed(); long duration = System.currentTimeMillis() - startTime; // 记录成功日志 log.info("导出操作 {} 执行成功，耗时: {}ms", methodName, duration); // 发送监控指标 Metrics.counter("export.operation.success", "method", methodName).increment(); Metrics.timer("export.operation.duration", "method", methodName) .record(duration, TimeUnit.MILLISECONDS); return result; } catch (Exception e) { long duration = System.currentTimeMillis() - startTime; // 记录失败日志 log.error("导出操作 {} 执行失败，耗时: {}ms", methodName, duration, e); // 发送失败监控 Metrics.counter("export.operation.failure", "method", methodName).increment(); throw e; } } } // 自定义注解用于标记导出操作 @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface ExportOperation { String value() default ""; }

4.2 安全与权限控制

导出功能往往涉及敏感数据，必须做好权限控制：

@RestController @RequestMapping("/api/secure-export") public class SecureExportController { @GetMapping("/sensitive-data") @PreAuthorize("hasRole('ADMIN') or hasPermission(#request, 'EXPORT_SENSITIVE')") @ExportOperation("敏感数据导出") public void exportSensitiveData( HttpServletResponse response, @CurrentUser UserPrincipal user, ExportRequest request) { // 记录操作日志 auditLogService.logExportOperation(user, "sensitive-data", request); // 验证导出频率限制 rateLimitService.checkExportLimit(user.getId()); // 执行导出 // ... } @GetMapping("/audit-logs") @PreAuthorize("@exportPermissionChecker.canExportAuditLogs(#user)") public void exportAuditLogs( HttpServletResponse response, @CurrentUser UserPrincipal user, @Valid ExportQuery query) { // 数据脱敏处理 List<AuditLogExportModel> logs = auditLogService.getLogsForExport(query) .stream() .map(this::maskSensitiveData) // 脱敏处理 .collect(Collectors.toList()); // 执行导出 // ... } private AuditLogExportModel maskSensitiveData(AuditLog log) { AuditLogExportModel model = convertToModel(log); // 对敏感字段进行脱敏 if (model.getIpAddress() != null) { model.setIpAddress(maskIpAddress(model.getIpAddress())); } if (model.getUserAgent() != null) { model.setUserAgent(truncateUserAgent(model.getUserAgent())); } return model; } }

4.3 异步导出与进度查询

对于耗时的导出任务，应该提供异步导出和进度查询功能：

@Service @Slf4j public class AsyncExportService { @Autowired private ThreadPoolTaskExecutor exportTaskExecutor; @Autowired private ExportTaskRepository taskRepository; @Autowired private ApplicationEventPublisher eventPublisher; public String startAsyncExport(ExportRequest request, UserPrincipal user) { String taskId = UUID.randomUUID().toString(); ExportTask task = new ExportTask(); task.setTaskId(taskId); task.setUserId(user.getId()); task.setStatus(ExportStatus.PENDING); task.setRequestParams(JsonUtils.toJson(request)); task.setCreatedAt(new Date()); taskRepository.save(task); // 提交异步任务 exportTaskExecutor.execute(() -> { try { updateTaskStatus(taskId, ExportStatus.PROCESSING, 0); // 执行导出逻辑 String fileUrl = executeExport(request, taskId); updateTaskStatus(taskId, ExportStatus.COMPLETED, 100, fileUrl); // 发送完成通知 eventPublisher.publishEvent(new ExportCompletedEvent(taskId, user.getEmail())); } catch (Exception e) { log.error("异步导出任务失败: {}", taskId, e); updateTaskStatus(taskId, ExportStatus.FAILED, 0, null, e.getMessage()); } }); return taskId; } public ExportProgress getExportProgress(String taskId) { ExportTask task = taskRepository.findByTaskId(taskId) .orElseThrow(() -> new ResourceNotFoundException("导出任务不存在")); ExportProgress progress = new ExportProgress(); progress.setTaskId(taskId); progress.setStatus(task.getStatus()); progress.setProgress(task.getProgress()); progress.setFileUrl(task.getFileUrl()); progress.setErrorMessage(task.getErrorMessage()); progress.setCreatedAt(task.getCreatedAt()); progress.setCompletedAt(task.getCompletedAt()); return progress; } private void updateTaskStatus(String taskId, ExportStatus status, Integer progress, String fileUrl, String errorMessage) { // 更新任务状态 // ... } }

在实际使用中，我发现异步导出结合WebSocket实时推送进度能给用户带来更好的体验。前端可以通过轮询或WebSocket获取导出进度，完成后直接提供下载链接。

5. 常见问题排查与调试技巧

5.1 文件名乱码问题深度解决

文件名乱码可能是导出功能中最常见的问题。不同的浏览器对Content-Disposition头的处理方式不同，下面是我总结的兼容性解决方案：

public static String encodeFileName(HttpServletRequest request, String fileName) throws UnsupportedEncodingException { String userAgent = request.getHeader("User-Agent"); String encodedFileName; if (userAgent != null) { // 处理不同浏览器的编码 if (userAgent.contains("MSIE") || userAgent.contains("Trident")) { // IE浏览器 encodedFileName = URLEncoder.encode(fileName, "UTF-8"); } else if (userAgent.contains("Firefox")) { // Firefox浏览器 encodedFileName = new String(fileName.getBytes(StandardCharsets.UTF_8), StandardCharsets.ISO_8859_1); } else if (userAgent.contains("Chrome") || userAgent.contains("Safari")) { // Chrome/Safari浏览器 - 使用RFC 5987 encodedFileName = URLEncoder.encode(fileName, "UTF-8") .replaceAll("\\+", "%20"); } else { // 其他浏览器 encodedFileName = URLEncoder.encode(fileName, "UTF-8"); } } else { // 默认处理 encodedFileName = URLEncoder.encode(fileName, "UTF-8"); } return encodedFileName; }

更现代的解决方案是使用Content-Disposition的filename*参数，它遵循RFC 5987标准：

public static void setFileDownloadHeader(HttpServletResponse response, String fileName) throws UnsupportedEncodingException { String encodedFileName = URLEncoder.encode(fileName, "UTF-8") .replaceAll("\\+", "%20"); // 同时设置filename和filename*，让浏览器选择支持的方式 String headerValue = String.format( "attachment; filename=\"%s.xlsx\"; filename*=UTF-8''%s.xlsx", encodedFileName, encodedFileName); response.setHeader("Content-Disposition", headerValue); }

5.2 内存泄漏排查与优化

EasyExcel虽然以内存优化著称，但在不当使用时仍可能出现内存问题。下面是一些排查技巧：

监控内存使用

@GetMapping("/export-with-metrics") public void exportWithMemoryMonitor(HttpServletResponse response) throws IOException { // 记录开始时的内存状态 Runtime runtime = Runtime.getRuntime(); long startMemory = runtime.totalMemory() - runtime.freeMemory(); setResponseHeaders(response, "监控导出"); ServletOutputStream outputStream = response.getOutputStream(); try { List<LargeDataModel> data = generateLargeData(100000); EasyExcel.write(outputStream, LargeDataModel.class) .registerWriteHandler(new AnalysisEventListener<LargeDataModel>() { @Override public void invoke(LargeDataModel data, AnalysisContext context) { // 处理每一行数据 } @Override public void doAfterAllAnalysed(AnalysisContext context) { // 所有数据解析完成后的处理 long endMemory = runtime.totalMemory() - runtime.freeMemory(); long memoryUsed = endMemory - startMemory; log.info("导出完成，内存使用: {} MB", memoryUsed / 1024 / 1024); } }) .sheet() .doWrite(data); } finally { // 强制垃圾回收（仅用于调试） System.gc(); long finalMemory = runtime.totalMemory() - runtime.freeMemory(); log.info("最终内存使用: {} MB", finalMemory / 1024 / 1024); } }

常见内存问题及解决方案

5.3 性能测试与调优

对于生产环境的导出功能，性能测试是必不可少的。下面是一个简单的性能测试方案：

@SpringBootTest @Slf4j public class ExportPerformanceTest { @Autowired private ExportService exportService; @Test public void testLargeDataExportPerformance() { int[] dataSizes = {1000, 10000, 100000, 500000}; for (int size : dataSizes) { log.info("开始测试数据量: {}", size); long startTime = System.currentTimeMillis(); long startMemory = getUsedMemory(); // 执行导出 byte[] result = exportService.exportTestData(size); long endTime = System.currentTimeMillis(); long endMemory = getUsedMemory(); long duration = endTime - startTime; long memoryUsed = endMemory - startMemory; log.info("数据量: {}, 耗时: {}ms, 内存使用: {}MB, 文件大小: {}KB", size, duration, memoryUsed / 1024 / 1024, result.length / 1024); // 断言性能要求 assertTrue(duration < getMaxDurationForSize(size), "导出时间超过预期: " + duration + "ms"); assertTrue(memoryUsed < getMaxMemoryForSize(size), "内存使用超过预期: " + memoryUsed + "bytes"); } } private long getUsedMemory() { Runtime runtime = Runtime.getRuntime(); return runtime.totalMemory() - runtime.freeMemory(); } private long getMaxDurationForSize(int size) { // 根据数据量设置合理的超时时间 if (size <= 10000) return 5000; // 5秒 else if (size <= 100000) return 30000; // 30秒 else return 120000; // 2分钟 } private long getMaxMemoryForSize(int size) { // 根据数据量设置合理的内存限制 return size * 1024L; // 每行约1KB } }

在实际项目中，我还会使用JMeter或Gatling进行压力测试，模拟多用户并发导出的场景。

6. 扩展功能与高级应用

6.1 多Sheet导出与复杂报表

EasyExcel支持导出包含多个Sheet的Excel文件，这对于需要分类展示的数据非常有用：

public void exportMultiSheetReport(HttpServletResponse response) throws IOException { setResponseHeaders(response, "多Sheet报表"); ServletOutputStream outputStream = response.getOutputStream(); ExcelWriter excelWriter = EasyExcel.write(outputStream).build(); try { // Sheet 1: 用户基本信息 WriteSheet userSheet = EasyExcel.writerSheet(0, "用户信息") .head(UserBasicModel.class) .build(); List<UserBasicModel> userData = getUserBasicData(); excelWriter.write(userData, userSheet); // Sheet 2: 用户订单信息 WriteSheet orderSheet = EasyExcel.writerSheet(1, "订单信息") .head(OrderModel.class) .build(); List<OrderModel> orderData = getOrderData(); excelWriter.write(orderData, orderSheet); // Sheet 3: 统计报表 WriteSheet statsSheet = EasyExcel.writerSheet(2, "统计报表") .head(StatisticsModel.class) .registerWriteHandler(new CellWriteHandler() { @Override public void afterCellDispose(WriteSheetHolder writeSheetHolder, WriteTableHolder writeTableHolder, List<CellData> cellDataList, Cell cell, Head head, Integer relativeRowIndex, Boolean isHead) { // 自定义单元格处理逻辑 if (!isHead && cell.getColumnIndex() == 3) { // 对第四列的数据进行特殊格式化 CellStyle style = writeSheetHolder.getSheet().getWorkbook() .createCellStyle(); style.setDataFormat( writeSheetHolder.getSheet().getWorkbook() .createDataFormat() .getFormat("#,##0.00")); cell.setCellStyle(style); } } }) .build(); List<StatisticsModel> statsData = getStatisticsData(); excelWriter.write(statsData, statsSheet); // Sheet 4: 图表（需要POI支持） WriteSheet chartSheet = EasyExcel.writerSheet(3, "图表") .head(ChartDataModel.class) .build(); List<ChartDataModel> chartData = getChartData(); excelWriter.write(chartData, chartSheet); // 添加图表（这里需要直接操作POI） addChartToSheet(excelWriter.writeContext().writeSheetHolder().getSheet()); } finally { if (excelWriter != null) { excelWriter.finish(); } } }

6.2 动态列导出

在某些业务场景中，需要导出的列是动态的，比如用户自定义报表。EasyExcel可以通过编程方式动态构建表头：

public void exportDynamicColumns(HttpServletResponse response, List<String> selectedColumns) throws IOException { setResponseHeaders(response, "动态列报表"); ServletOutputStream outputStream = response.getOutputStream(); // 动态构建表头 List<List<String>> head = new ArrayList<>(); // 添加固定列 head.add(Collections.singletonList("ID")); head.add(Collections.singletonList("姓名")); // 添加动态列 for (String column : selectedColumns) { head.add(Collections.singletonList(column)); } // 动态构建数据 List<List<Object>> data = new ArrayList<>(); for (User user : getAllUsers()) { List<Object> rowData = new ArrayList<>(); rowData.add(user.getId()); rowData.add(user.getName()); // 根据选择的列添加数据 for (String column : selectedColumns) { Object value = getDynamicColumnValue(user, column); rowData.add(value); } data.add(rowData); } // 执行导出 EasyExcel.write(outputStream) .head(head) .sheet("动态报表") .doWrite(data); } private Object getDynamicColumnValue(User user, String column) { // 根据列名获取对应的数据 switch (column) { case "年龄": return user.getAge(); case "邮箱": return user.getEmail(); case "注册时间": return user.getRegisterTime(); case "状态": return user.getStatus(); default: return ""; } }

6.3 导出功能的前端集成

虽然本文主要关注后端实现，但一个完整的导出功能也需要前端配合。这里简单提一下前端集成的要点：

// 前端导出函数示例 async function exportData(params) { try { // 显示加载状态 showLoading('正在生成导出文件...'); // 构建查询参数 const queryParams = new URLSearchParams(params); // 发起导出请求 const response = await fetch(`/api/export/users?${queryParams}`, { method: 'GET', headers: { 'Authorization': `Bearer ${getToken()}`, }, }); if (!response.ok) { throw new Error(`导出失败: ${response.statusText}`); } // 获取文件名 const contentDisposition = response.headers.get('Content-Disposition'); let filename = 'export.xlsx'; if (contentDisposition) { const matches = /filename[^;=\n]*=((['"]).*?\2|[^;\n]*)/.exec(contentDisposition); if (matches != null && matches[1]) { filename = matches[1].replace(/['"]/g, ''); // 解码文件名 filename = decodeURIComponent(filename); } } // 创建Blob并下载 const blob = await response.blob(); const url = window.URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = filename; document.body.appendChild(a); a.click(); window.URL.revokeObjectURL(url); document.body.removeChild(a); // 显示成功消息 showSuccess('导出成功，文件已开始下载'); } catch (error) { console.error('导出失败:', error); showError(`导出失败: ${error.message}`); } finally { hideLoading(); } } // 对于大文件导出，可以显示进度 function exportLargeDataWithProgress(params) { return new Promise((resolve, reject) => { const taskId = startAsyncExport(params); // 轮询查询进度 const intervalId = setInterval(async () => { try { const progress = await getExportProgress(taskId); updateProgressBar(progress.percentage); if (progress.status === 'COMPLETED') { clearInterval(intervalId); downloadExportedFile(progress.fileUrl); resolve(); } else if (progress.status === 'FAILED') { clearInterval(intervalId); reject(new Error(progress.errorMessage)); } } catch (error) { clearInterval(intervalId); reject(error); } }, 1000); // 每秒查询一次进度 }); }

在实际项目中，我遇到过各种奇怪的导出问题，从浏览器的兼容性问题到服务器内存配置，从网络超时到权限验证。每个问题都需要具体分析，但有了上面这些基础框架和最佳实践，大部分问题都能快速定位和解决。