1. 工作台接口从一堆表里捞出一个“驾驶舱”连载到第14篇烘焙坊项目的后端已经攒了不少东西商品、订单、会员、库存、供应商采购……数据都在各自的表里躺着。可老板和管理员登录后台后第一眼看到的不能只是一张清单而是得有个能反映门店当前状况的“驾驶舱”——今天卖了多少钱、出了多少单、哪些商品快卖完了、最近有没有异常。这个页面就是工作台Dashboard它背后需要后端提供一个聚合接口把散落在多张表里的数据汇总成一份结构化响应。这个接口不见得有多高深的技术含量但特别容易做得不舒服。难点在于三件事统计口径要统一、查询不能拖慢页面、数据结构要稳定。先说统计口径比如“今日营收”严格一点应该怎么算是用户下单就算还是支付成功才算退款订单要不要冲减如果砍单也计入营收月底对账的时候财务肯定跟你急。我们这套系统定的口径是今日营收 今天支付成功且未退款的订单金额合计今日订单数 今天创建的订单数量。口径定下来之后所有统计逻辑必须围绕这个规则写不能一个接口一个说法。再就是性能问题。工作台页面刚打开就要同时查订单数、营业额、会员增量、热销商品、待办提醒……如果每次都实时去全表扫订单量一旦上来接口响应就是灾难。所以正常的做法是常规统计用定时任务或缓存兜底必要时再走实时计算的降级路径。我们在项目里给工作台接口加了一层缓存统计结果缓存5分钟热销榜缓存10分钟这样即便门店高峰期同时多个管理员刷新页面数据库的压力也可控。数据结构设计上也有讲究。前端要渲染趋势图、占比图、排行列表如果后端返回的字段前端还要二次加工那就耦合了。我们约定工作台接口统一返回下面这种树形结构{ summary: { todayOrderCount: 128, todayRevenue: 15680.50, todayNewMemberCount: 12, pendingShippingCount: 6, lowStockCount: 3 }, hotProducts: [ { productId: 1001, name: 原味吐司, soldCount: 58 } ], weekRevenueTrend: [ { date: 2024-11-11, revenue: 2200.00 } ], recentOrders: [ { orderNo: BF202411130018, memberName: 王**, amount: 88.50, status: paid } ] }字段用驼峰命名数量类字段直接给数字日期类字段统一字符串金额统一为带两位小数的 BigDecimal。前端只需要把它塞进图表组件里就行不用再做二次映射。这种“后端把数据切好前端只管吃”的思路其实也适用于大多数管理后台的工作台接口。1.1 工作台数据聚合的SQL套路工作台接口的核心是聚合查询。我这边用的是 MyBatis-Plus但统计类的需求不建议派上用场用它的 Wrapper 硬写SQL 复杂到一定程度还是 XML 里写原生 SQL 更清楚。下面是几个最常用的统计SQL直接照抄基本能跑今日订单数和营收SELECT COUNT(*) AS todayOrderCount, COALESCE(SUM(CASE WHEN pay_status 1 AND refund_status ! 1 THEN total_amount END), 0) AS todayRevenue FROM orders WHERE create_time CURDATE()这里要注意两点COUNT(*) 统计的是今天创建的所有订单不管有没有支付SUM 里则用 CASE WHEN 做了过滤只累计支付成功且没退款的金额。COALESCE 防 NULLSUM 在没有匹配行时返回 NULL前端拿到 null 就麻了所以一定要兜底为 0。一周营收趋势按天分组SELECT DATE(create_time) AS statDate, COALESCE(SUM(CASE WHEN pay_status 1 AND refund_status ! 1 THEN total_amount END), 0) AS revenue FROM orders WHERE create_time DATE_SUB(CURDATE(), INTERVAL 6 DAY) GROUP BY DATE(create_time)返回结果只有有订单的日期前端画趋势图时没有数据的日期要补 0。这个补 0 可以在 SQL 层做也可以在后端代码里补。SQL 层做要额外生成日期序列代码里做更简单遍历过去7天遇到缺失日期就补 0。我建议在后端代码里补逻辑更直观也方便后续调整统计范围。热销商品榜从订单明细表聚合SELECT p.id AS productId, p.name AS productName, SUM(oi.quantity) AS soldCount FROM order_items oi JOIN orders o ON oi.order_id o.id JOIN products p ON oi.product_id p.id WHERE o.create_time CURDATE() AND o.pay_status 1 GROUP BY p.id, p.name ORDER BY soldCount DESC LIMIT 10这种SQL在高并发业务下会锁多张表但烘焙店进销存系统并发有限加上有缓存兜底完全没问题。如果是千万级订单量的电商系统这种实时聚合就得换离线数仓或ES了。咱们做项目要分清场景不是每个方案都上重型组件。1.2 工作台数据组装与服务层设计聚合查询拿到的是三块数据汇总数、趋势列表、排行榜。在服务层把它们组装到一起时我建议建一个 WorkbenchOverviewDTO而不是把 Map 到处传。Map 虽然写着快但过两个月回过头来看字段名要“猜谜”完全没有类型约束。Service RequiredArgsConstructor public class WorkbenchService { private final OrderMapper orderMapper; private final RedisTemplateString, Object redisTemplate; Autowired private StringRedisSerializer stringRedisSerializer; public WorkbenchOverviewDTO getOverview() { String cacheKey workbench:overview: LocalDate.now(); Object cached redisTemplate.opsForValue().get(cacheKey); if (cached ! null) { return (WorkbenchOverviewDTO) cached; } WorkbenchOverviewDTO dto new WorkbenchOverviewDTO(); dto.setSummary(buildSummary()); dto.setHotProducts(orderMapper.selectHotProducts(10)); dto.setWeekRevenueTrend(fillMissingDates(orderMapper.selectWeekRevenueTrend(), 7)); dto.setRecentOrders(orderMapper.selectRecentOrders(10)); redisTemplate.opsForValue().set(cacheKey, dto, 5, TimeUnit.MINUTES); return dto; } }这里有个小坑要提醒RedisTemplate 直接存 DTO必须要配置序列化器。项目里早期用 JDK 默认序列化Debug 时看到一堆乱码后来统一改成 JSON 序列化编程体验才正常。前端如果直接对接这个接口还需要在后端把 LocalDate、LocalDateTime 的序列化格式统一处理最简单的是在配置文件里设置spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8就这样工作台的接口雏形已经能跑了。接下来看第二个重头戏导出数据报表。2. 导出数据报表需求五分钟做起来五个小时很多开发者看不起导出功能觉得不就是查出来再写进 Excel 嘛。真做了才知道导出是最容易翻车的一类功能。数据量小的时候POI 一把梭没问题一旦单表数据过十万直接内存溢出给你看。更别说还有中文文件名乱码、字段对不齐、日期格式不对、金额精度丢失这些“慢性病”。我们烘焙坊项目的导出需求主要有三类订单明细报表、商品销售统计报表、每日经营汇总报表。老板的原始需求很朴实“我要把这一周的单子导出来在 Excel 里看看到底哪个面包卖得好。”但落到后端就得设计一套稳定的导出机制而不是每个报表都单独写一套导出代码。先做技术选型。Java 生态里做 Excel 导出主流方案大概有三类原生 Apache POI、阿里 EasyExcel、直接输出 CSV。我直接给结论如果项目是 Spring Boot 技术栈导出数据量可能在万级甚至更高又希望控制内存EasyExcel 是性价比最高的选项。为什么不用原生 POIPOI 的读写模型是先把整个工作簿加载进内存做过一次百万行导出测试耗时能接受但内存占用直接飙到 1.5GB 以上在小服务器上分分钟 OOM。EasyExcel 用的是 SAX 模式逐行解析写入不需要一次性把全部数据装进内存十万行数据导出的峰值内存可以控制在几十 MB 左右这个差别是决定性的。当然POI 也有它的优势比如对样式、公式、复杂合并单元格的控制更精细但报表导出场景根本用不上那些高级功能。CSV 是最轻量的写个流就能输出但中文在低版本 Excel 里容易乱码而且不支持多 sheet老板要的“按日分页”有点难做。综合判断EasyExcel 胜出。2.1 报表导出技术选型对比方案内存占用支持大数据量样式控制开发成本适用场景Apache POI高容易 OOM强高复杂格式、模板填充EasyExcel低支持流式读写中等低大部分报表导出CSV极低支持弱极低RPA / 数据交换这里补充一点EasyExcel 底层仍然依赖 POI但封装程度很高咱们平时只用到 ExcelProperty 注解和 WriteSheet 几个类真正的细节都被藏起来了。这也意味着出了问题Debug 时可能要翻它的源码但日常开发完全够用。2.2 导出数据的异步化改造报表导出还有一个隐蔽的坑同步导出在数据量大时会让HTTP请求长时间挂起。网关默认超时时间通常60秒数据库复杂查询加文件生成一不小心就超时前端拿不到响应用户只会看到“请求失败”。要做成可靠的导出功能必须走异步任务。异步导出的架构很简单前端点击导出按钮后端先创建一个导出任务立即返回“任务创建成功稍后下载”的提示。后台线程池异步执行查询、写文件、上传或写入本地存储/OSS完成后把生成的文件地址更新到任务记录里。前端再通过轮询或 WebSocket 拿到状态展示下载入口。项目里目前还是简单的轮询方案每3秒查一次任务状态。任务表设计长这样CREATE TABLE export_task ( id BIGINT PRIMARY KEY AUTO_INCREMENT, task_no VARCHAR(32) NOT NULL COMMENT 任务编号, export_type VARCHAR(32) NOT NULL COMMENT 报表类型ORDER/SELL/DAILY, file_path VARCHAR(255) COMMENT 生成后的文件路径, status TINYINT NOT NULL DEFAULT 0 COMMENT 0待执行 1执行中 2完成 3失败, create_time DATETIME NOT NULL, finish_time DATETIME NULL, fail_reason VARCHAR(255) COMMENT 失败原因 );任务提交时先生成一条 status0 的记录返回 taskNo。线程池消费任务后把状态改成执行中、完成或失败。这套机制的好处是随时可以查导出历史后续还能加入“下载次数”“文件过期清理”等功能。有的团队会加一个天级定时任务把超过24小时的历史导出文件从磁盘删掉避免磁盘被占满。2.3 异步导出任务的设计与实现线程池要单独建不能用框架默认的公共线程池否则导出任务和业务请求互相抢线程接口会被拖垮。项目里建议用一个独立配置的线程池Configuration public class ExportThreadPoolConfig { Bean(exportExecutor) public ThreadPoolTaskExecutor exportExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(2); executor.setMaxPoolSize(4); executor.setQueueCapacity(20); executor.setThreadNamePrefix(export-); executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); executor.initialize(); return executor; } }核心线程数没必要太多因为导出是 IO 密集型任务同时跑三四个就会占满磁盘 IO 和数据库连接。拒绝策略用 CallerRunsPolicy 而不是 AbortPolicy这样任务队列满时不会直接抛异常而是由调用线程也就是 Controller 所在线程继续执行至少保证任务不丢失。提交任务的代码PostMapping(/export/order) public ResultString exportOrderReport(RequestBody ExportOrderRequest request) { ExportTask task exportTaskService.createTask(ORDER); exportExecutor.execute(() - { try { exportTaskService.markRunning(task.getId()); String filePath orderReportExporter.export(request); exportTaskService.markFinished(task.getId(), filePath); } catch (Exception e) { log.error(订单报表导出失败, e); exportTaskService.markFailed(task.getId(), e.getMessage()); } }); return Result.success(task.getTaskNo()); }这里有一个容易被忽略的点Controller 里异步任务的入参 request 对象是在主线程创建的lambda 表达式里使用它时要确保它的字段是不可变的。3. 订单报表导出的核心实现从查询到文件生成接下来是重头戏订单报表导出的完整实现。先看数据模型。订单主表 orders 存订单号、用户ID、支付状态、金额、下单时间订单明细表 order_items 存商品ID、数量、单价、小计。导出报表时老板希望一行数据展示一个订单的状态和明细数量所以我们查主表再关联明细表统计行数。实现步骤按顺序拆解校验导出条件时间范围、订单状态组装查询条件创建 EasyExcel 的 ExcelWriter从数据库流式读取数据重点步骤写 Excel 文件返回文件路径。3.1 订单报表导出的完整实现步骤首先是实体类定义使用 ExcelProperty 注解来控制列头public class OrderExportRow { ExcelProperty(下单时间) private String orderTime; ExcelProperty(订单号) private String orderNo; ExcelProperty(会员姓名) private String memberName; ExcelProperty(订单金额) private BigDecimal totalAmount; ExcelProperty(支付状态) private String payStatus; ExcelProperty(商品数量) private Integer totalQuantity; }字段命名要语义化别用 a、b、c 这种Excel 列头就直接拿注解里的字符串做表头如果实体字段名定义不好代码可读性也会受影响。查询部分我特意说一个很多教程没讲透的点导出大表时一定要用流式查询不能一次性把 List 查出来再写。MyBatis 支持 Cursor 接口它返回一个游标只有在遍历时才分批从数据库取数据。在 XML 里声明方式很简单select idscanOrderExportData resultTypeOrderExportRow SELECT DATE_FORMAT(o.create_time, %Y-%m-%d %H:%i:%s) AS orderTime, o.order_no AS orderNo, COALESCE(m.real_name, 散客) AS memberName, o.total_amount AS totalAmount, CASE o.pay_status WHEN 1 THEN 已支付 WHEN 2 THEN 待支付 ELSE 已退款 END AS payStatus, (SELECT COUNT(*) FROM order_items oi WHERE oi.order_id o.id) AS totalQuantity FROM orders o LEFT JOIN members m ON o.member_id m.id where if teststartTime ! null AND o.create_time #{startTime} /if if testendTime ! null AND o.create_time lt; #{endTime} /if if testpayStatus ! null AND o.pay_status #{payStatus} /if /where ORDER BY o.create_time /selectService 层接收 Cursor 后遍历写入 Excelpublic String exportOrderReport(ExportOrderRequest request) { String fileName 订单报表_ System.currentTimeMillis() .xlsx; String filePath exportFileDir fileName; try (CursorOrderExportRow cursor orderMapper.scanOrderExportData(request); ExcelWriter writer EasyExcel.write(filePath, OrderExportRow.class) .inMemory(false) .build()) { WriteSheet sheet EasyExcel.writerSheet(订单明细).build(); int rowCount 0; for (OrderExportRow row : cursor) { writer.write(Collections.singletonList(row), sheet); rowCount; } // 写一个表尾统计行 if (rowCount 0) { ListOrderExportRow totalRow Collections.singletonList( buildTotalRow(rowCount, request.getStartTime())); writer.write(totalRow, sheet); } } catch (IOException e) { throw new ExportException(导出失败, e); } return filePath; }关键点在于inMemory(false)这个参数明确告诉 EasyExcel 不要把所有数据缓存在内存里。inMemory(true)只适合数据量很小、需要多次操作的情况大数据量导出必须关闭它。写入文件后需要给前端一个可访问的下载 URL。如果服务部署在单机直接把文件放进静态资源目录配置一个映射即可。如果是集群部署或者服务器重启后文件会丢就应该上传到对象存储或共享存储。这个项目是先写本地盘配置了下面这段资源映射spring: web: resources: static-locations: file:${export.dir}/,classpath:/static/然后下载地址就可以是http://域名/export/订单报表_xxx.xlsx。上传到 OSS 的代码也不难主要是加一个上传的客户端调用这里先不展开。3.2 商品销售统计报表的多 Sheet 分组写入商品销售统计报表比订单报表更复杂一点因为老板要求“按日分 sheet哪天卖得好一眼就能扫出来”。实现思路是查询日期范围内的销售明细按日期分组每个日期单独写一个 sheet。ListDailySellSummary summaries sellMapper.selectDailySellSummary(startDate, endDate); MapString, ListDailySellSummary grouped summaries.stream() .collect(Collectors.groupingBy(s - s.getStatDate().toString())); try (ExcelWriter writer EasyExcel.write(filePath).build()) { for (Map.EntryString, ListDailySellSummary entry : grouped.entrySet()) { WriteSheet sheet EasyExcel.writerSheet(entry.getKey(), DailySellSummary.class).build(); writer.write(entry.getValue(), sheet); } }这里有个问题如果日期范围跨了 30 天就会生成 30 个 sheetExcel 文档本身没问题但文件打开时要等一会儿。更合理的方案是只对老板指定生成的日期分 sheet其他日期统一汇总在一个 sheet 里。这个逻辑很灵活用一行代码区分一下就行。分组之后sellMapper 的 SQL 也比订单报表更聚合SELECT DATE(o.create_time) AS statDate, p.name AS productName, SUM(oi.quantity) AS soldQuantity, SUM(oi.quantity * oi.unit_price) AS soldAmount FROM order_items oi JOIN orders o ON oi.order_id o.id JOIN products p ON oi.product_id p.id WHERE o.create_time BETWEEN #{startDate} AND #{endDate} AND o.pay_status 1 GROUP BY DATE(o.create_time), p.id, p.name ORDER BY statDate, soldQuantity DESC注意这种报表统计的是“支付成功的订单”中的商品销售情况不统计退款订单。如果退款也要算业务方需要给一个明确的定义否则后续对账会扯皮。4. 导出类问题的排查技巧乱码、OOM、打不开文件导出功能的坑一路踩下来也不少。有些问题甚至不是代码逻辑问题而是环境配置问题。这里列几个我实际碰到的典型案例。4.1 中文乱码的排查思路中文乱码分两种文件名的乱码和 Excel 内容的乱码。文件名乱码最常见的原因是 HTTP 响应头里没有正确设置 Content-Disposition 的编码格式。Spring Boot 里下载接口直接设置 UTF-8 编码response.setHeader(Content-Disposition, attachment;filename URLEncoder.encode(fileName, StandardCharsets.UTF_8).replaceAll(\\, %20));URLEncoder.encode 会把空格转成 Excel 不认所以要 replaceAll 替换为 %20。另一个坑是浏览器端解码不一致某些低版本浏览器对百分号编码的中文文件名处理有问题解决办法是同时提供 filename* UTF-8 的 RFC 5987 格式不过现在主流浏览器基本都处理好了。内容乱码则是 EasyExcel 写入时字符集的问题。EasyExcel 底层生成的 xlsx 用的是 XML 格式本身就是 UTF-8一般不会乱码。如果你用的是 POI 生成 CSV 文件那就要在输出流上指定 UTF-8 的 BOM 头outputStream.write(new byte[]{(byte) 0xEF, (byte) 0xBB, (byte) 0xBF});没有 BOM 头Excel 打开 CSV 时就容易按系统默认编码常见的是 GBK解析结果就是一团乱码。4.2 导出时内存溢出的处理实录有一次测试环境导出十万行订单报表直接报了 OOM堆内存被撑爆。排查后发现是代码里习惯性地先selectList查出全量 List再交给 EasyExcel 写。这是一个低级的“思维惯性”错误——既然 EasyExcel 号称能搞定大数据量那就必须配合 Cursor 流式查询两边对齐才能发挥效果。// 错误写法全量查询内存直接炸 ListOrderExportRow list orderMapper.selectList(condition); EasyExcel.write(filePath).sheet().doWrite(list); // 正确写法游标流式读取 CursorOrderExportRow cursor orderMapper.scanOrderExportData(condition);另外还要提醒一句MyBatis 的 Cursor 使用完后必须关闭。用 try-with-resource 包裹是最稳妥的或者至少要在 finally 块里 close。否则数据库连接会被一直占着后面请求一来数据库连接池直接被打满。4.3 生成的文件打不开或字段对不齐文件打不开十有八九是文件没写完就返回了下载地址。异步任务里生成的代码可能抛了异常但任务状态被误标记为完成。所以任务完成标记一定要放在 try 块的末尾而不是 catch 之后。正确做法是只在所有数据写入完毕、流正常关闭之后才置为“完成”任何异常都走 catch 分支把失败原因写清楚置为“失败”。字段对不齐的问题主要是 EasyExcel 注解里的字段顺序和数据库查询出来的列顺序不一致。EasyExcel 默认按实体类字段声明顺序排序跟 SQL 查出来的列顺序没关系但如果你用 Map 接收结果写入顺序不确定就可能错位。建议始终用 DTO 作为resultType避免用 Map 应付了事。5. 多线程分页导出与超大 sheet 拆分的进阶玩法如果数据量继续增大单 sheet 超过 Excel 上限1048576 行也就是 2^20即使 EasyExcel 不 OOMExcel 本身也打不开了。此时有两种处理方案一是按查询条件拆分多个文件打成 ZIP 包下载二是一个文件多个 sheet每个 sheet 装一批数据。前者更稳定后者在 Excel 里查看更方便。我实现过一个“多条件订单导出”功能查询范围是一个季度预计能导出 30 万行。单个 sheet 行数限制内可接受但为了保险还是按渠道拆成了两个 sheet线上订单一个 sheet线下门店订单一个 sheet。实现时只需要在查询条件里增加一个 channel 参数然后循环写入不同 sheetfor (String channel : channels) { ListOrderExportRow rows orderMapper.selectByChannel(channel, start, end); WriteSheet sheet EasyExcel.writerSheet(channelNameMap.get(channel), OrderExportRow.class).build(); writer.write(rows, sheet); }无论单 sheet 还是多 sheet写完文件后验一下文件大小和行数是很有必要的。之前我在测试时就发现过某个报表导出后文件只有 1KB明显数据没写进去排查发现是查询条件里把日期参数传反了导致查出来的数据为空。给导出任务加一个CHECKSUM也好或者在日志里打印导出行数方便定位。5.1 大数据量导出与 sheet 拆分注意事项拆 sheet 不是无脑拆得结合业务看。一个 sheet 行数接近上限时Excel 打开时间会明显变长尤其老版本 Office 可能直接崩溃。所以我个人的经验是单 sheet 超过 20 万行就建议拆开别硬冲上限。拆的键可以选日期、渠道、门店、商品分类以业务上“统计视角”为单位这样老板打开文件看数据的体验才好。同时每个 sheet 的列宽也需要设置一下不然商品名称字段和金额字段挤成一团。EasyExcel 提供了 ColumnWidthStyleStrategy 做自适应列宽WriteHandler columnWidthStyle new LongestMatchColumnWidthStyleStrategy(); EasyExcel.write(filePath, OrderExportRow.class) .registerWriteHandler(columnWidthStyle) .sheet(订单明细) .doWrite(rows);自适应列宽的原理是扫描当前 sheet 的所有单元格内容找最长的那条来定宽度。但这个方法在数据量极大的时候性能很差因为要多扫描一次大数据量时更推荐手动设置合理列宽比如订单号 24、时间列 20、金额列 12。5.2 利用多线程分页查询提升导出效率查询数据本身也可能是导出瓶颈。如果数据表有百万行单线程流式查询再快也要分钟级。在条件允许时可以按主键 ID 分段用多线程并行查询再汇总写入。但注意并行写入同一个 ExcelWriter 是不安全的容易产生数据错乱。安全的做法是每个线程负责一个 sheet最后单独合并或者线程各自生成临时 CSV 文件最后再统一汇总。实操起来代码量会上升不少性价比得自己判断。普通的烘焙坊后台订单量一年撑死几十万行单线程流式导出完全够用没必要为了炫技引入多线程复杂度。如果你的项目确实要导出百万行建议先想想产品层面是否允许分批导出、异步压缩下载而不是一味在技术层面硬扛。6. 报表导出缓存与性能优化的实战记录报表导出功能上线后数据库压力明显上升。原因是导出任务往往伴随复杂统计反复查询同一张表而且容易集中在月底月初办公室几个管理员同时点导出连接池瞬间被打满。我们做了一次针对性的优化核心思路是“结果复用”。订单报表、销售报表这种常用报表如果查询条件相同时间范围、门店、状态短时间内导出的数据完全一样。我们加了一层查询结果缓存以时间范围状态为 key把查询出来的数据序列化到 Redis有效期 20 分钟。第二次导出时直接读缓存跳过数据库查询生成文件的速度从几十秒降到几秒。但这里有个原则性问题缓存不能用于实时性要求高的数据。比如“今日营收”这种页面展示数据缓存时间就不能太长5 分钟以内是合理值。报表导出则不同老板看的大多是历史数据20 分钟的缓存几乎不影响体验。实现时用 Spring Cache 注解或者手动 Redis 操作都行。6.1 报表查询的缓存策略public ListOrderExportRow loadOrderData(ExportOrderRequest request) { String cacheKey export:order: request.getStartTime() : request.getEndTime() : request.getPayStatus(); ListOrderExportRow cached (ListOrderExportRow) redisTemplate.opsForValue().get(cacheKey); if (cached ! null) { return cached; } ListOrderExportRow rows orderMapper.scanOrderExportData(request); redisTemplate.opsForValue().set(cacheKey, rows, 20, TimeUnit.MINUTES); return rows; }注意这里用 Cursor 流式查出来后转成 List数据全装进内存了。如果数据量超过十万行不建议这么缓存内存压力太大。分页查、或者只缓存统计结果而不缓存明细行也是一种折中。实际项目里我倾向于对“统计报表”做缓存对“明细导出”不做缓存因为明细数据量大且唯一性强缓存价值不大。6.2 报表导出过程中的常见异常处理导出模块的异常处理可以单独提炼一个工具类统一捕获和返回提示。分类大致三类参数异常时间范围超过 90 天、没有选中门店、必填项为空直接拒绝返回业务错误码数据异常目标数据不存在、金额合计有负值可以正常导出但要在日志中标记警告系统异常文件写入失败、磁盘空间不足、线程池队列满捕获后标记任务失败写入失败原因并释放资源。错误消息尽量写人话比如“所选时间范围内没有订单数据”而不是抛一个空指针给前端。实际开发中很多人只关注功能跑通没注意异常信息质量结果运营遇到问题只能抱着图来问开发体验极差。7. 工作台报表联动与后续扩展思路工作台和导出现在可以相互配合了。工作台展示的数据是“快照”导出报表是“底稿”。我看代码里已经加了一个入口工作台页面上每个统计卡片旁边带一个“导出今日报表”按钮点击之后走的就是异步导出任务。这样管理员每天开早会的时候点一下按钮就能拿到数据不需要再进报表中心一级级筛选。这种联动在后端实现上不复杂工作台接口里给每个模块附带一个导出类型标识点击按钮时前端拿这个标识去调导出接口后端根据标识创建对应类型的导出任务。如果后续要支持定时推送报表到企业微信或者邮件这套任务机制已经铺垫好了只需要加一个定时调度器每天凌晨跑一次导出任务再把文件发出去就行。7.1 从导出功能延伸到定时报表推送定时报表推送是个很实用的扩展。我们项目里的计划是每天上午 9 点将前一天的经营汇总报表自动导出并发送到管理群。实现方案不复杂在已有的 exportTask 机制上设置一张定时任务配置表存报表类型、发送时间和接收人然后用 Spring 的Scheduled注解调度一个扫描任务到了时间就触发一次导出发完消息后记录日志。Scheduled(cron 0 0 9 * * ?) public void autoExportDailyReport() { ExportOrderRequest request new ExportOrderRequest(); request.setStartTime(LocalDate.now().minusDays(1).atStartOfDay()); request.setEndTime(LocalDate.now().atStartOfDay()); exportOrderReport(request); }定时任务别用简单粗暴的Scheduled一把梭如果任务执行时间超过调度间隔会出现任务堆积。建议在任务里加分布式锁或者用一个状态位标记是否正在执行防止重复触发。7.2 前端配合要点任务轮询与下载导出按钮点击后前端要处理的不只是一个结果还涉及三个状态任务创建成功、任务执行中、任务完成。创建成功时弹出提示“报表后台生成中请稍候下载”执行中展示 loading 或者进度条完成后展示一个下载按钮。轮询接口很轻量GetMapping(/export/status/{taskNo}) public ResultExportTaskVO getTaskStatus(PathVariable String taskNo) { return Result.success(exportTaskService.getStatus(taskNo)); }前端每 3 秒调一次状态为 2 时拿到 filePath拼上服务地址直接跳转下载状态为 3 时弹窗显示失败原因。这套交互在用户感知上比一直“请求中”强很多能避免重复点击导出按钮导致服务端任务堆积。8. 个人实操总结与避坑清单烘焙坊项目的后端连载到这里工作台和导出报表已经完成。这两块功能虽然技术深度不算高但是很考验接口设计能力、数据统计能力以及异常情况下的兜底能力。我个人在这两轮开发中体会最深的有三点。第一统计功能必须提前定义好口径。咱们系统里“今日营收”的定义是支付成功且未退款这个口径是产品、财务、后端三方对齐之后定的。如果当初不明确后面导出的报表和对账单就会对不上那是比较大的事故。不管工作台还是导出统计口径最好统一成一套常量或枚举管理避免各写各的。第二导出类操作尽量不要做成同步的任务化是标配。就算现在数据量小同步导出体验也还行但等订单量上来会非常被动。线程池、任务表、状态查询、资源清理这些代码一次性搭好后面做任何导出都能复用这个投资非常划算。第三数据量的判断要客观。EasyExcel 确实解决了大数据量导出的内存问题但如果你的数据已经有几十万上百万行第一步还是要先确认是不是真的要导这么多。很多时候业务方只需要汇总导出明细反而是一种“偷懒式需求”。和产品沟通清楚再动手能省下大量无畏的开发时间。最后分享一个容易被忽略的细节所有导出文件的生成路径和管理最好集中在一个配置类或常量类里不要散落在代码各处。项目组后来新增了一个导出归档功能就是把已下载过的文件自动迁移到冷存储目录结果发现导出路径在十几个类里硬编码差点没被坑死。后来统一集中到 FileStorageService 里做收口才彻底改干净。如果你现在也踩过类似的坑能早一天重构就早一天做越晚成本越高。 
长河君 · 2026/10/16 3:55:41 · 阅读 1.2k 工作台接口与报表导出实战：EasyExcel异步化与缓存优化
1. 工作台接口从一堆表里捞出一个“驾驶舱”连载到第14篇烘焙坊项目的后端已经攒了不少东西商品、订单、会员、库存、供应商采购……数据都在各自的表里躺着。可老板和管理员登录后台后第一眼看到的不能只是一张清单而是得有个能反映门店当前状况的“驾驶舱”——今天卖了多少钱、出了多少单、哪些商品快卖完了、最近有没有异常。这个页面就是工作台Dashboard它背后需要后端提供一个聚合接口把散落在多张表里的数据汇总成一份结构化响应。这个接口不见得有多高深的技术含量但特别容易做得不舒服。难点在于三件事统计口径要统一、查询不能拖慢页面、数据结构要稳定。先说统计口径比如“今日营收”严格一点应该怎么算是用户下单就算还是支付成功才算退款订单要不要冲减如果砍单也计入营收月底对账的时候财务肯定跟你急。我们这套系统定的口径是今日营收 今天支付成功且未退款的订单金额合计今日订单数 今天创建的订单数量。口径定下来之后所有统计逻辑必须围绕这个规则写不能一个接口一个说法。再就是性能问题。工作台页面刚打开就要同时查订单数、营业额、会员增量、热销商品、待办提醒……如果每次都实时去全表扫订单量一旦上来接口响应就是灾难。所以正常的做法是常规统计用定时任务或缓存兜底必要时再走实时计算的降级路径。我们在项目里给工作台接口加了一层缓存统计结果缓存5分钟热销榜缓存10分钟这样即便门店高峰期同时多个管理员刷新页面数据库的压力也可控。数据结构设计上也有讲究。前端要渲染趋势图、占比图、排行列表如果后端返回的字段前端还要二次加工那就耦合了。我们约定工作台接口统一返回下面这种树形结构{ summary: { todayOrderCount: 128, todayRevenue: 15680.50, todayNewMemberCount: 12, pendingShippingCount: 6, lowStockCount: 3 }, hotProducts: [ { productId: 1001, name: 原味吐司, soldCount: 58 } ], weekRevenueTrend: [ { date: 2024-11-11, revenue: 2200.00 } ], recentOrders: [ { orderNo: BF202411130018, memberName: 王**, amount: 88.50, status: paid } ] }字段用驼峰命名数量类字段直接给数字日期类字段统一字符串金额统一为带两位小数的 BigDecimal。前端只需要把它塞进图表组件里就行不用再做二次映射。这种“后端把数据切好前端只管吃”的思路其实也适用于大多数管理后台的工作台接口。1.1 工作台数据聚合的SQL套路工作台接口的核心是聚合查询。我这边用的是 MyBatis-Plus但统计类的需求不建议派上用场用它的 Wrapper 硬写SQL 复杂到一定程度还是 XML 里写原生 SQL 更清楚。下面是几个最常用的统计SQL直接照抄基本能跑今日订单数和营收SELECT COUNT(*) AS todayOrderCount, COALESCE(SUM(CASE WHEN pay_status 1 AND refund_status ! 1 THEN total_amount END), 0) AS todayRevenue FROM orders WHERE create_time CURDATE()这里要注意两点COUNT(*) 统计的是今天创建的所有订单不管有没有支付SUM 里则用 CASE WHEN 做了过滤只累计支付成功且没退款的金额。COALESCE 防 NULLSUM 在没有匹配行时返回 NULL前端拿到 null 就麻了所以一定要兜底为 0。一周营收趋势按天分组SELECT DATE(create_time) AS statDate, COALESCE(SUM(CASE WHEN pay_status 1 AND refund_status ! 1 THEN total_amount END), 0) AS revenue FROM orders WHERE create_time DATE_SUB(CURDATE(), INTERVAL 6 DAY) GROUP BY DATE(create_time)返回结果只有有订单的日期前端画趋势图时没有数据的日期要补 0。这个补 0 可以在 SQL 层做也可以在后端代码里补。SQL 层做要额外生成日期序列代码里做更简单遍历过去7天遇到缺失日期就补 0。我建议在后端代码里补逻辑更直观也方便后续调整统计范围。热销商品榜从订单明细表聚合SELECT p.id AS productId, p.name AS productName, SUM(oi.quantity) AS soldCount FROM order_items oi JOIN orders o ON oi.order_id o.id JOIN products p ON oi.product_id p.id WHERE o.create_time CURDATE() AND o.pay_status 1 GROUP BY p.id, p.name ORDER BY soldCount DESC LIMIT 10这种SQL在高并发业务下会锁多张表但烘焙店进销存系统并发有限加上有缓存兜底完全没问题。如果是千万级订单量的电商系统这种实时聚合就得换离线数仓或ES了。咱们做项目要分清场景不是每个方案都上重型组件。1.2 工作台数据组装与服务层设计聚合查询拿到的是三块数据汇总数、趋势列表、排行榜。在服务层把它们组装到一起时我建议建一个 WorkbenchOverviewDTO而不是把 Map 到处传。Map 虽然写着快但过两个月回过头来看字段名要“猜谜”完全没有类型约束。Service RequiredArgsConstructor public class WorkbenchService { private final OrderMapper orderMapper; private final RedisTemplateString, Object redisTemplate; Autowired private StringRedisSerializer stringRedisSerializer; public WorkbenchOverviewDTO getOverview() { String cacheKey workbench:overview: LocalDate.now(); Object cached redisTemplate.opsForValue().get(cacheKey); if (cached ! null) { return (WorkbenchOverviewDTO) cached; } WorkbenchOverviewDTO dto new WorkbenchOverviewDTO(); dto.setSummary(buildSummary()); dto.setHotProducts(orderMapper.selectHotProducts(10)); dto.setWeekRevenueTrend(fillMissingDates(orderMapper.selectWeekRevenueTrend(), 7)); dto.setRecentOrders(orderMapper.selectRecentOrders(10)); redisTemplate.opsForValue().set(cacheKey, dto, 5, TimeUnit.MINUTES); return dto; } }这里有个小坑要提醒RedisTemplate 直接存 DTO必须要配置序列化器。项目里早期用 JDK 默认序列化Debug 时看到一堆乱码后来统一改成 JSON 序列化编程体验才正常。前端如果直接对接这个接口还需要在后端把 LocalDate、LocalDateTime 的序列化格式统一处理最简单的是在配置文件里设置spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8就这样工作台的接口雏形已经能跑了。接下来看第二个重头戏导出数据报表。2. 导出数据报表需求五分钟做起来五个小时很多开发者看不起导出功能觉得不就是查出来再写进 Excel 嘛。真做了才知道导出是最容易翻车的一类功能。数据量小的时候POI 一把梭没问题一旦单表数据过十万直接内存溢出给你看。更别说还有中文文件名乱码、字段对不齐、日期格式不对、金额精度丢失这些“慢性病”。我们烘焙坊项目的导出需求主要有三类订单明细报表、商品销售统计报表、每日经营汇总报表。老板的原始需求很朴实“我要把这一周的单子导出来在 Excel 里看看到底哪个面包卖得好。”但落到后端就得设计一套稳定的导出机制而不是每个报表都单独写一套导出代码。先做技术选型。Java 生态里做 Excel 导出主流方案大概有三类原生 Apache POI、阿里 EasyExcel、直接输出 CSV。我直接给结论如果项目是 Spring Boot 技术栈导出数据量可能在万级甚至更高又希望控制内存EasyExcel 是性价比最高的选项。为什么不用原生 POIPOI 的读写模型是先把整个工作簿加载进内存做过一次百万行导出测试耗时能接受但内存占用直接飙到 1.5GB 以上在小服务器上分分钟 OOM。EasyExcel 用的是 SAX 模式逐行解析写入不需要一次性把全部数据装进内存十万行数据导出的峰值内存可以控制在几十 MB 左右这个差别是决定性的。当然POI 也有它的优势比如对样式、公式、复杂合并单元格的控制更精细但报表导出场景根本用不上那些高级功能。CSV 是最轻量的写个流就能输出但中文在低版本 Excel 里容易乱码而且不支持多 sheet老板要的“按日分页”有点难做。综合判断EasyExcel 胜出。2.1 报表导出技术选型对比方案内存占用支持大数据量样式控制开发成本适用场景Apache POI高容易 OOM强高复杂格式、模板填充EasyExcel低支持流式读写中等低大部分报表导出CSV极低支持弱极低RPA / 数据交换这里补充一点EasyExcel 底层仍然依赖 POI但封装程度很高咱们平时只用到 ExcelProperty 注解和 WriteSheet 几个类真正的细节都被藏起来了。这也意味着出了问题Debug 时可能要翻它的源码但日常开发完全够用。2.2 导出数据的异步化改造报表导出还有一个隐蔽的坑同步导出在数据量大时会让HTTP请求长时间挂起。网关默认超时时间通常60秒数据库复杂查询加文件生成一不小心就超时前端拿不到响应用户只会看到“请求失败”。要做成可靠的导出功能必须走异步任务。异步导出的架构很简单前端点击导出按钮后端先创建一个导出任务立即返回“任务创建成功稍后下载”的提示。后台线程池异步执行查询、写文件、上传或写入本地存储/OSS完成后把生成的文件地址更新到任务记录里。前端再通过轮询或 WebSocket 拿到状态展示下载入口。项目里目前还是简单的轮询方案每3秒查一次任务状态。任务表设计长这样CREATE TABLE export_task ( id BIGINT PRIMARY KEY AUTO_INCREMENT, task_no VARCHAR(32) NOT NULL COMMENT 任务编号, export_type VARCHAR(32) NOT NULL COMMENT 报表类型ORDER/SELL/DAILY, file_path VARCHAR(255) COMMENT 生成后的文件路径, status TINYINT NOT NULL DEFAULT 0 COMMENT 0待执行 1执行中 2完成 3失败, create_time DATETIME NOT NULL, finish_time DATETIME NULL, fail_reason VARCHAR(255) COMMENT 失败原因 );任务提交时先生成一条 status0 的记录返回 taskNo。线程池消费任务后把状态改成执行中、完成或失败。这套机制的好处是随时可以查导出历史后续还能加入“下载次数”“文件过期清理”等功能。有的团队会加一个天级定时任务把超过24小时的历史导出文件从磁盘删掉避免磁盘被占满。2.3 异步导出任务的设计与实现线程池要单独建不能用框架默认的公共线程池否则导出任务和业务请求互相抢线程接口会被拖垮。项目里建议用一个独立配置的线程池Configuration public class ExportThreadPoolConfig { Bean(exportExecutor) public ThreadPoolTaskExecutor exportExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(2); executor.setMaxPoolSize(4); executor.setQueueCapacity(20); executor.setThreadNamePrefix(export-); executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); executor.initialize(); return executor; } }核心线程数没必要太多因为导出是 IO 密集型任务同时跑三四个就会占满磁盘 IO 和数据库连接。拒绝策略用 CallerRunsPolicy 而不是 AbortPolicy这样任务队列满时不会直接抛异常而是由调用线程也就是 Controller 所在线程继续执行至少保证任务不丢失。提交任务的代码PostMapping(/export/order) public ResultString exportOrderReport(RequestBody ExportOrderRequest request) { ExportTask task exportTaskService.createTask(ORDER); exportExecutor.execute(() - { try { exportTaskService.markRunning(task.getId()); String filePath orderReportExporter.export(request); exportTaskService.markFinished(task.getId(), filePath); } catch (Exception e) { log.error(订单报表导出失败, e); exportTaskService.markFailed(task.getId(), e.getMessage()); } }); return Result.success(task.getTaskNo()); }这里有一个容易被忽略的点Controller 里异步任务的入参 request 对象是在主线程创建的lambda 表达式里使用它时要确保它的字段是不可变的。3. 订单报表导出的核心实现从查询到文件生成接下来是重头戏订单报表导出的完整实现。先看数据模型。订单主表 orders 存订单号、用户ID、支付状态、金额、下单时间订单明细表 order_items 存商品ID、数量、单价、小计。导出报表时老板希望一行数据展示一个订单的状态和明细数量所以我们查主表再关联明细表统计行数。实现步骤按顺序拆解校验导出条件时间范围、订单状态组装查询条件创建 EasyExcel 的 ExcelWriter从数据库流式读取数据重点步骤写 Excel 文件返回文件路径。3.1 订单报表导出的完整实现步骤首先是实体类定义使用 ExcelProperty 注解来控制列头public class OrderExportRow { ExcelProperty(下单时间) private String orderTime; ExcelProperty(订单号) private String orderNo; ExcelProperty(会员姓名) private String memberName; ExcelProperty(订单金额) private BigDecimal totalAmount; ExcelProperty(支付状态) private String payStatus; ExcelProperty(商品数量) private Integer totalQuantity; }字段命名要语义化别用 a、b、c 这种Excel 列头就直接拿注解里的字符串做表头如果实体字段名定义不好代码可读性也会受影响。查询部分我特意说一个很多教程没讲透的点导出大表时一定要用流式查询不能一次性把 List 查出来再写。MyBatis 支持 Cursor 接口它返回一个游标只有在遍历时才分批从数据库取数据。在 XML 里声明方式很简单select idscanOrderExportData resultTypeOrderExportRow SELECT DATE_FORMAT(o.create_time, %Y-%m-%d %H:%i:%s) AS orderTime, o.order_no AS orderNo, COALESCE(m.real_name, 散客) AS memberName, o.total_amount AS totalAmount, CASE o.pay_status WHEN 1 THEN 已支付 WHEN 2 THEN 待支付 ELSE 已退款 END AS payStatus, (SELECT COUNT(*) FROM order_items oi WHERE oi.order_id o.id) AS totalQuantity FROM orders o LEFT JOIN members m ON o.member_id m.id where if teststartTime ! null AND o.create_time #{startTime} /if if testendTime ! null AND o.create_time lt; #{endTime} /if if testpayStatus ! null AND o.pay_status #{payStatus} /if /where ORDER BY o.create_time /selectService 层接收 Cursor 后遍历写入 Excelpublic String exportOrderReport(ExportOrderRequest request) { String fileName 订单报表_ System.currentTimeMillis() .xlsx; String filePath exportFileDir fileName; try (CursorOrderExportRow cursor orderMapper.scanOrderExportData(request); ExcelWriter writer EasyExcel.write(filePath, OrderExportRow.class) .inMemory(false) .build()) { WriteSheet sheet EasyExcel.writerSheet(订单明细).build(); int rowCount 0; for (OrderExportRow row : cursor) { writer.write(Collections.singletonList(row), sheet); rowCount; } // 写一个表尾统计行 if (rowCount 0) { ListOrderExportRow totalRow Collections.singletonList( buildTotalRow(rowCount, request.getStartTime())); writer.write(totalRow, sheet); } } catch (IOException e) { throw new ExportException(导出失败, e); } return filePath; }关键点在于inMemory(false)这个参数明确告诉 EasyExcel 不要把所有数据缓存在内存里。inMemory(true)只适合数据量很小、需要多次操作的情况大数据量导出必须关闭它。写入文件后需要给前端一个可访问的下载 URL。如果服务部署在单机直接把文件放进静态资源目录配置一个映射即可。如果是集群部署或者服务器重启后文件会丢就应该上传到对象存储或共享存储。这个项目是先写本地盘配置了下面这段资源映射spring: web: resources: static-locations: file:${export.dir}/,classpath:/static/然后下载地址就可以是http://域名/export/订单报表_xxx.xlsx。上传到 OSS 的代码也不难主要是加一个上传的客户端调用这里先不展开。3.2 商品销售统计报表的多 Sheet 分组写入商品销售统计报表比订单报表更复杂一点因为老板要求“按日分 sheet哪天卖得好一眼就能扫出来”。实现思路是查询日期范围内的销售明细按日期分组每个日期单独写一个 sheet。ListDailySellSummary summaries sellMapper.selectDailySellSummary(startDate, endDate); MapString, ListDailySellSummary grouped summaries.stream() .collect(Collectors.groupingBy(s - s.getStatDate().toString())); try (ExcelWriter writer EasyExcel.write(filePath).build()) { for (Map.EntryString, ListDailySellSummary entry : grouped.entrySet()) { WriteSheet sheet EasyExcel.writerSheet(entry.getKey(), DailySellSummary.class).build(); writer.write(entry.getValue(), sheet); } }这里有个问题如果日期范围跨了 30 天就会生成 30 个 sheetExcel 文档本身没问题但文件打开时要等一会儿。更合理的方案是只对老板指定生成的日期分 sheet其他日期统一汇总在一个 sheet 里。这个逻辑很灵活用一行代码区分一下就行。分组之后sellMapper 的 SQL 也比订单报表更聚合SELECT DATE(o.create_time) AS statDate, p.name AS productName, SUM(oi.quantity) AS soldQuantity, SUM(oi.quantity * oi.unit_price) AS soldAmount FROM order_items oi JOIN orders o ON oi.order_id o.id JOIN products p ON oi.product_id p.id WHERE o.create_time BETWEEN #{startDate} AND #{endDate} AND o.pay_status 1 GROUP BY DATE(o.create_time), p.id, p.name ORDER BY statDate, soldQuantity DESC注意这种报表统计的是“支付成功的订单”中的商品销售情况不统计退款订单。如果退款也要算业务方需要给一个明确的定义否则后续对账会扯皮。4. 导出类问题的排查技巧乱码、OOM、打不开文件导出功能的坑一路踩下来也不少。有些问题甚至不是代码逻辑问题而是环境配置问题。这里列几个我实际碰到的典型案例。4.1 中文乱码的排查思路中文乱码分两种文件名的乱码和 Excel 内容的乱码。文件名乱码最常见的原因是 HTTP 响应头里没有正确设置 Content-Disposition 的编码格式。Spring Boot 里下载接口直接设置 UTF-8 编码response.setHeader(Content-Disposition, attachment;filename URLEncoder.encode(fileName, StandardCharsets.UTF_8).replaceAll(\\, %20));URLEncoder.encode 会把空格转成 Excel 不认所以要 replaceAll 替换为 %20。另一个坑是浏览器端解码不一致某些低版本浏览器对百分号编码的中文文件名处理有问题解决办法是同时提供 filename* UTF-8 的 RFC 5987 格式不过现在主流浏览器基本都处理好了。内容乱码则是 EasyExcel 写入时字符集的问题。EasyExcel 底层生成的 xlsx 用的是 XML 格式本身就是 UTF-8一般不会乱码。如果你用的是 POI 生成 CSV 文件那就要在输出流上指定 UTF-8 的 BOM 头outputStream.write(new byte[]{(byte) 0xEF, (byte) 0xBB, (byte) 0xBF});没有 BOM 头Excel 打开 CSV 时就容易按系统默认编码常见的是 GBK解析结果就是一团乱码。4.2 导出时内存溢出的处理实录有一次测试环境导出十万行订单报表直接报了 OOM堆内存被撑爆。排查后发现是代码里习惯性地先selectList查出全量 List再交给 EasyExcel 写。这是一个低级的“思维惯性”错误——既然 EasyExcel 号称能搞定大数据量那就必须配合 Cursor 流式查询两边对齐才能发挥效果。// 错误写法全量查询内存直接炸 ListOrderExportRow list orderMapper.selectList(condition); EasyExcel.write(filePath).sheet().doWrite(list); // 正确写法游标流式读取 CursorOrderExportRow cursor orderMapper.scanOrderExportData(condition);另外还要提醒一句MyBatis 的 Cursor 使用完后必须关闭。用 try-with-resource 包裹是最稳妥的或者至少要在 finally 块里 close。否则数据库连接会被一直占着后面请求一来数据库连接池直接被打满。4.3 生成的文件打不开或字段对不齐文件打不开十有八九是文件没写完就返回了下载地址。异步任务里生成的代码可能抛了异常但任务状态被误标记为完成。所以任务完成标记一定要放在 try 块的末尾而不是 catch 之后。正确做法是只在所有数据写入完毕、流正常关闭之后才置为“完成”任何异常都走 catch 分支把失败原因写清楚置为“失败”。字段对不齐的问题主要是 EasyExcel 注解里的字段顺序和数据库查询出来的列顺序不一致。EasyExcel 默认按实体类字段声明顺序排序跟 SQL 查出来的列顺序没关系但如果你用 Map 接收结果写入顺序不确定就可能错位。建议始终用 DTO 作为resultType避免用 Map 应付了事。5. 多线程分页导出与超大 sheet 拆分的进阶玩法如果数据量继续增大单 sheet 超过 Excel 上限1048576 行也就是 2^20即使 EasyExcel 不 OOMExcel 本身也打不开了。此时有两种处理方案一是按查询条件拆分多个文件打成 ZIP 包下载二是一个文件多个 sheet每个 sheet 装一批数据。前者更稳定后者在 Excel 里查看更方便。我实现过一个“多条件订单导出”功能查询范围是一个季度预计能导出 30 万行。单个 sheet 行数限制内可接受但为了保险还是按渠道拆成了两个 sheet线上订单一个 sheet线下门店订单一个 sheet。实现时只需要在查询条件里增加一个 channel 参数然后循环写入不同 sheetfor (String channel : channels) { ListOrderExportRow rows orderMapper.selectByChannel(channel, start, end); WriteSheet sheet EasyExcel.writerSheet(channelNameMap.get(channel), OrderExportRow.class).build(); writer.write(rows, sheet); }无论单 sheet 还是多 sheet写完文件后验一下文件大小和行数是很有必要的。之前我在测试时就发现过某个报表导出后文件只有 1KB明显数据没写进去排查发现是查询条件里把日期参数传反了导致查出来的数据为空。给导出任务加一个CHECKSUM也好或者在日志里打印导出行数方便定位。5.1 大数据量导出与 sheet 拆分注意事项拆 sheet 不是无脑拆得结合业务看。一个 sheet 行数接近上限时Excel 打开时间会明显变长尤其老版本 Office 可能直接崩溃。所以我个人的经验是单 sheet 超过 20 万行就建议拆开别硬冲上限。拆的键可以选日期、渠道、门店、商品分类以业务上“统计视角”为单位这样老板打开文件看数据的体验才好。同时每个 sheet 的列宽也需要设置一下不然商品名称字段和金额字段挤成一团。EasyExcel 提供了 ColumnWidthStyleStrategy 做自适应列宽WriteHandler columnWidthStyle new LongestMatchColumnWidthStyleStrategy(); EasyExcel.write(filePath, OrderExportRow.class) .registerWriteHandler(columnWidthStyle) .sheet(订单明细) .doWrite(rows);自适应列宽的原理是扫描当前 sheet 的所有单元格内容找最长的那条来定宽度。但这个方法在数据量极大的时候性能很差因为要多扫描一次大数据量时更推荐手动设置合理列宽比如订单号 24、时间列 20、金额列 12。5.2 利用多线程分页查询提升导出效率查询数据本身也可能是导出瓶颈。如果数据表有百万行单线程流式查询再快也要分钟级。在条件允许时可以按主键 ID 分段用多线程并行查询再汇总写入。但注意并行写入同一个 ExcelWriter 是不安全的容易产生数据错乱。安全的做法是每个线程负责一个 sheet最后单独合并或者线程各自生成临时 CSV 文件最后再统一汇总。实操起来代码量会上升不少性价比得自己判断。普通的烘焙坊后台订单量一年撑死几十万行单线程流式导出完全够用没必要为了炫技引入多线程复杂度。如果你的项目确实要导出百万行建议先想想产品层面是否允许分批导出、异步压缩下载而不是一味在技术层面硬扛。6. 报表导出缓存与性能优化的实战记录报表导出功能上线后数据库压力明显上升。原因是导出任务往往伴随复杂统计反复查询同一张表而且容易集中在月底月初办公室几个管理员同时点导出连接池瞬间被打满。我们做了一次针对性的优化核心思路是“结果复用”。订单报表、销售报表这种常用报表如果查询条件相同时间范围、门店、状态短时间内导出的数据完全一样。我们加了一层查询结果缓存以时间范围状态为 key把查询出来的数据序列化到 Redis有效期 20 分钟。第二次导出时直接读缓存跳过数据库查询生成文件的速度从几十秒降到几秒。但这里有个原则性问题缓存不能用于实时性要求高的数据。比如“今日营收”这种页面展示数据缓存时间就不能太长5 分钟以内是合理值。报表导出则不同老板看的大多是历史数据20 分钟的缓存几乎不影响体验。实现时用 Spring Cache 注解或者手动 Redis 操作都行。6.1 报表查询的缓存策略public ListOrderExportRow loadOrderData(ExportOrderRequest request) { String cacheKey export:order: request.getStartTime() : request.getEndTime() : request.getPayStatus(); ListOrderExportRow cached (ListOrderExportRow) redisTemplate.opsForValue().get(cacheKey); if (cached ! null) { return cached; } ListOrderExportRow rows orderMapper.scanOrderExportData(request); redisTemplate.opsForValue().set(cacheKey, rows, 20, TimeUnit.MINUTES); return rows; }注意这里用 Cursor 流式查出来后转成 List数据全装进内存了。如果数据量超过十万行不建议这么缓存内存压力太大。分页查、或者只缓存统计结果而不缓存明细行也是一种折中。实际项目里我倾向于对“统计报表”做缓存对“明细导出”不做缓存因为明细数据量大且唯一性强缓存价值不大。6.2 报表导出过程中的常见异常处理导出模块的异常处理可以单独提炼一个工具类统一捕获和返回提示。分类大致三类参数异常时间范围超过 90 天、没有选中门店、必填项为空直接拒绝返回业务错误码数据异常目标数据不存在、金额合计有负值可以正常导出但要在日志中标记警告系统异常文件写入失败、磁盘空间不足、线程池队列满捕获后标记任务失败写入失败原因并释放资源。错误消息尽量写人话比如“所选时间范围内没有订单数据”而不是抛一个空指针给前端。实际开发中很多人只关注功能跑通没注意异常信息质量结果运营遇到问题只能抱着图来问开发体验极差。7. 工作台报表联动与后续扩展思路工作台和导出现在可以相互配合了。工作台展示的数据是“快照”导出报表是“底稿”。我看代码里已经加了一个入口工作台页面上每个统计卡片旁边带一个“导出今日报表”按钮点击之后走的就是异步导出任务。这样管理员每天开早会的时候点一下按钮就能拿到数据不需要再进报表中心一级级筛选。这种联动在后端实现上不复杂工作台接口里给每个模块附带一个导出类型标识点击按钮时前端拿这个标识去调导出接口后端根据标识创建对应类型的导出任务。如果后续要支持定时推送报表到企业微信或者邮件这套任务机制已经铺垫好了只需要加一个定时调度器每天凌晨跑一次导出任务再把文件发出去就行。7.1 从导出功能延伸到定时报表推送定时报表推送是个很实用的扩展。我们项目里的计划是每天上午 9 点将前一天的经营汇总报表自动导出并发送到管理群。实现方案不复杂在已有的 exportTask 机制上设置一张定时任务配置表存报表类型、发送时间和接收人然后用 Spring 的Scheduled注解调度一个扫描任务到了时间就触发一次导出发完消息后记录日志。Scheduled(cron 0 0 9 * * ?) public void autoExportDailyReport() { ExportOrderRequest request new ExportOrderRequest(); request.setStartTime(LocalDate.now().minusDays(1).atStartOfDay()); request.setEndTime(LocalDate.now().atStartOfDay()); exportOrderReport(request); }定时任务别用简单粗暴的Scheduled一把梭如果任务执行时间超过调度间隔会出现任务堆积。建议在任务里加分布式锁或者用一个状态位标记是否正在执行防止重复触发。7.2 前端配合要点任务轮询与下载导出按钮点击后前端要处理的不只是一个结果还涉及三个状态任务创建成功、任务执行中、任务完成。创建成功时弹出提示“报表后台生成中请稍候下载”执行中展示 loading 或者进度条完成后展示一个下载按钮。轮询接口很轻量GetMapping(/export/status/{taskNo}) public ResultExportTaskVO getTaskStatus(PathVariable String taskNo) { return Result.success(exportTaskService.getStatus(taskNo)); }前端每 3 秒调一次状态为 2 时拿到 filePath拼上服务地址直接跳转下载状态为 3 时弹窗显示失败原因。这套交互在用户感知上比一直“请求中”强很多能避免重复点击导出按钮导致服务端任务堆积。8. 个人实操总结与避坑清单烘焙坊项目的后端连载到这里工作台和导出报表已经完成。这两块功能虽然技术深度不算高但是很考验接口设计能力、数据统计能力以及异常情况下的兜底能力。我个人在这两轮开发中体会最深的有三点。第一统计功能必须提前定义好口径。咱们系统里“今日营收”的定义是支付成功且未退款这个口径是产品、财务、后端三方对齐之后定的。如果当初不明确后面导出的报表和对账单就会对不上那是比较大的事故。不管工作台还是导出统计口径最好统一成一套常量或枚举管理避免各写各的。第二导出类操作尽量不要做成同步的任务化是标配。就算现在数据量小同步导出体验也还行但等订单量上来会非常被动。线程池、任务表、状态查询、资源清理这些代码一次性搭好后面做任何导出都能复用这个投资非常划算。第三数据量的判断要客观。EasyExcel 确实解决了大数据量导出的内存问题但如果你的数据已经有几十万上百万行第一步还是要先确认是不是真的要导这么多。很多时候业务方只需要汇总导出明细反而是一种“偷懒式需求”。和产品沟通清楚再动手能省下大量无畏的开发时间。最后分享一个容易被忽略的细节所有导出文件的生成路径和管理最好集中在一个配置类或常量类里不要散落在代码各处。项目组后来新增了一个导出归档功能就是把已下载过的文件自动迁移到冷存储目录结果发现导出路径在十几个类里硬编码差点没被坑死。后来统一集中到 FileStorageService 里做收口才彻底改干净。如果你现在也踩过类似的坑能早一天重构就早一天做越晚成本越高。