前端大报表导出怎么选：浏览器直出还是后端异步任务

报表导出最容易踩的坑，不是 CSV 还是 Excel，而是把几万行数据塞进一次浏览器请求。数据量小时，前端直接生成文件最省事；一旦查询超过几十秒、结果接近浏览器可用内存，应该切到后端异步任务，再用进度事件通知页面，最后发一个短时下载地址。

先把导出任务按负载分成两条路

一个订单列表导出 3000 行，浏览器拿到 JSON 后用 Blob 组装 CSV，用户点击一次就结束。这条路径的优势是开发量小、没有任务表，也不用处理进度订阅。

但同样的代码放到月度财务报表上就会变得脆弱：查询慢、响应体大、标签页被系统回收、用户刷新后状态丢失，任何一个环节出错都要从头再来。这里先别急着加一个“更长超时”，超时只是把失败推迟。

浏览器直出：最小写法和边界

直出适合结果小、字段少、下载动作必须立即完成的场景。前端可以把已经拿到的数据转成 CSV，再通过对象 URL 触发下载：

function saveCsv(rows) {
  const body = rows.map(row => [row.id, row.amount, row.createdAt]
    .map(value => '"' + String(value ?? '').replaceAll('"', '""') + '"')
    .join(',')).join('\n');
  const blob = new Blob(['\ufeff' + body], { type: 'text/csv;charset=utf-8' });
  const url = URL.createObjectURL(blob);
  const link = document.createElement('a');
  link.href = url;
  link.download = 'orders.csv';
  link.click();
  URL.revokeObjectURL(url);
}

这个片段解决的是“已经在浏览器里的数据如何保存”，并没有解决大查询。实务上可把 1 万行以内、单行字段不超过 2 KB 作为谨慎起点，再用 Chrome Performance 和实际设备内存验证，而不是把它当成固定标准。

后端异步：把等待时间从页面请求中移走

复杂报表更适合拆成四步：创建任务、后台生成、推送状态、领取文件。任务表至少保存 id、user_id、status、progress、object_key 和 expires_at。页面刷新后按任务 ID 查询，导出不会因为标签页重载而丢失。

状态接口可以返回简单 JSON；需要实时体验时，用 SSE 让页面持续收到状态变化。SSE 是单向通道，正好适合服务端推送进度，取消任务仍然走普通的 POST 接口：

const events = new EventSource(`/api/report-tasks/${taskId}/events`);
events.addEventListener('progress', event => {
  const state = JSON.parse(event.data);
  renderProgress(state.status, state.progress);
  if (state.status === 'done' || state.status === 'failed') {
    events.close();
  }
});

后台完成文件后，不要直接把对象存储的永久地址塞进页面。服务端根据当前用户和任务状态签发一个短时 URL；页面拿到 done 状态后再请求下载地址。这个边界能同时照顾权限和过期清理。

用三个约束判断该不该异步

如果只满足“文件大”而不满足“生成慢”，也可以先评估流式响应或分页查询；如果还需要跨设备继续下载、审计和重试，异步任务的收益会更明显。

推荐的前端接口顺序

1. POST /api/report-tasks：提交筛选条件，返回 taskId，不要把原始 SQL 或超长条件直接放进下载 URL。
2. GET /api/report-tasks/{id}：刷新页面时恢复状态，前端只渲染服务端返回的百分比。
3. GET /api/report-tasks/{id}/events：任务运行中订阅 SSE；断线后按退避策略重新订阅。
4. POST /api/report-tasks/{id}/cancel：取消尚未完成的任务，服务端停止后续批次并标记为 cancelled。
5. GET /api/report-tasks/{id}/download：服务端再次检查归属、状态和过期时间，再返回短时对象地址。

前端只需要围绕这几个状态组织界面：queued 显示排队位置，running 显示进度，done 显示下载按钮，failed 显示错误和重试入口。不要用“进度 100%”推断文件一定可下载，真正的判断应来自后端的 done 状态和下载接口。

容易被忽略的失败和安全边界

进度条为什么会卡在 99%

生成数据和上传对象不是同一个阶段。建议把进度拆成查询、写文件、上传三个阶段，最后一次只在对象校验完成后改成 done。页面显示 99% 并不等于失败，应该给出“正在准备下载文件”的明确文案。

用户刷新后为什么看不到任务

不要把任务状态只放在内存或前端状态管理器里。用任务表持久化，页面启动时从最近任务接口恢复；事件订阅只是加速更新，不是唯一数据来源。

短时下载地址还需要权限判断吗

需要。签发地址前必须核对当前会话、任务归属、报表状态和有效期。对象存储的短时 URL 是交付凭证，不应替代业务授权。

相关问题

小报表也能统一走异步吗？

可以，但会增加任务表、状态展示和清理逻辑。若用户最在意点击后立刻拿到文件，小报表保留直出通常更顺手。

SSE 断线后要不要重建任务？

不用。先调用状态接口确认任务仍在运行，再重新订阅事件；任务 ID 不变，避免重复生成。

什么时候需要分片写文件？

当单次查询或内存占用成为瓶颈时，把数据按游标或时间范围分批写入临时文件，再上传最终对象。分片是生成策略，和页面是否使用 SSE 是两个独立决定。

落地前的检查清单

• 记录一次真实导出的行数、耗时、响应体大小和失败率。
• 为异步任务定义过期清理、取消、重试和失败原因。
• 确认刷新页面、网络断开、重复点击下载时状态仍然一致。
• 下载地址设置过期时间，并在签发前再次做用户和任务校验。