前端批量导出接口怎么设计：异步任务、状态查询和下载链接

后台系统里，“导出 Excel”是一个很常见的按钮。小数据量时，前端点一下就直接下载；但当筛选条件变复杂、数据量变大、生成时间超过几十秒后，同步下载接口就容易把页面拖住：浏览器没有进度，用户重复点击，网关超时，后端生成了一半也不知道该怎么提示。

本文从前端调用方体验出发，讨论批量导出接口怎么设计更稳：把一次下载拆成“创建导出任务、查询任务状态、拿下载链接”三段，让前端能展示进度、处理失败、避免重复提交，也方便后端做队列和文件过期清理。

接口目标：不要让下载请求承担生成报表

同步导出接口通常长这样：

GET /api/orders/export?status=paid&start=2026-06-01&end=2026-06-29

它的问题不是语法，而是职责太重。这个请求既要接收条件，又要查询数据，还要生成文件，最后再把二进制内容返回给浏览器。只要其中一步变慢，前端就只能等待一个不可见的长连接。

更清晰的接口目标是：下载接口只负责下载已经准备好的文件；生成文件由导出任务负责。这样前端拿到任务编号后，可以进入状态查询流程，而不是把页面卡在一个未知的下载请求上。

推荐拆成三个接口：

POST /api/report/export-jobs
GET  /api/report/export-jobs/{jobId}
GET  /api/report/export-jobs/{jobId}/download

第一个接口返回任务编号，第二个接口返回任务状态，第三个接口在文件准备好后返回下载地址或直接下载文件。前端可以围绕状态机做界面，而不是围绕一次长请求做猜测。

调用方需求：前端真正需要哪些状态

前端不是只需要一个 jobId，而是需要足够清楚的状态字段。建议任务状态至少包含下面这些信息：

{
  "jobId": "exp_20260629_153501",
  "status": "processing",
  "progress": 45,
  "fileName": "orders-20260629.xlsx",
  "downloadUrl": null,
  "failReason": "",
  "expiresAt": "2026-06-30T15:35:01+08:00"
}

status 用来驱动按钮和提示文案，progress 用来展示进度，downloadUrl 用来控制下载入口是否可见，expiresAt 告诉用户文件多久后会被清理。

状态值不宜太多，前端常用这几个就够了：

• pending：任务已创建，还没开始处理。
• processing：文件正在生成，可以展示进度。
• ready：文件已生成，可以下载。
• failed：生成失败，需要展示原因和重试入口。
• expired：文件已过期，需要重新发起导出。

参数设计：筛选条件、幂等键和文件格式

创建任务接口建议使用 POST，请求体里放筛选条件和导出选项。原因很简单：筛选条件可能较长，未来还会增加列选择、排序、时区、文件格式等配置。

{
  "bizType": "orders",
  "filters": {
    "status": "paid",
    "startDate": "2026-06-01",
    "endDate": "2026-06-29",
    "keyword": "VIP"
  },
  "columns": ["orderNo", "amount", "paidAt", "buyerName"],
  "format": "xlsx",
  "requestId": "orders-paid-20260629-001"
}

这里的 requestId 很重要。用户可能连续点击导出按钮，浏览器也可能因为网络抖动重试请求。服务端可以用 requestId 做幂等判断：同一个用户、同一个业务类型、同一个请求编号，只返回已有任务，不重复创建。

参数设计上有三个取舍：

• 筛选条件应复用列表页查询条件，避免“列表看到 100 条，导出变成 300 条”。
• 列配置要由服务端二次校验，前端传来的列不能绕过权限。
• 文件格式要白名单控制，比如只允许 xlsx、csv。

错误处理：把失败留在任务状态里

批量导出的错误不要只停留在创建任务接口的响应里。创建任务成功，只代表任务进入队列，不代表文件一定能生成成功。真正的失败可能发生在查询数据、生成文件、上传文件或清理临时文件阶段。

因此，状态查询接口应该把失败原因返回给前端：

{
  "jobId": "exp_20260629_153501",
  "status": "failed",
  "progress": 70,
  "downloadUrl": null,
  "failReason": "查询结果超过导出上限，请缩小时间范围",
  "retryable": true
}

前端拿到 failed 后，不要继续轮询。更好的交互是停止进度条，展示失败原因，并提供“调整条件”和“重新导出”两个动作。这样用户知道下一步该做什么，而不是看到一个一直转圈的按钮。

接口错误可以分两层处理：

• 创建任务阶段的参数错误，用 HTTP 状态码和字段错误提示直接返回。
• 任务处理阶段的业务失败，写入任务状态，由查询接口返回给前端。

兼容策略：从同步下载平滑迁移

已有系统通常不能一次性改完。可以先保留旧的同步下载接口，同时给新页面接入异步任务接口。为了让前端迁移成本可控，建议保持筛选参数语义一致：

const filters = collectListFilters();

await createExportJob({
  bizType: "orders",
  filters,
  columns: selectedColumns,
  format: "xlsx",
  requestId: buildRequestId(filters),
});

这样列表页原有的筛选条件收集逻辑可以继续使用，只是从“拼 URL 下载”变成“提交导出任务”。迁移时重点检查三件事：

• 列表查询和导出任务是否使用同一套筛选字段。
• 权限字段是否由后端重新判断，不能只相信前端传参。
• 旧下载入口是否在大数据量场景下提示用户使用新流程。

示例：一个可落地的导出调用流程

前端实现可以按下面的流程组织。代码只展示关键逻辑，实际项目里可以接入请求封装和组件状态管理。

async function startExport() {
  const payload = {
    bizType: "orders",
    filters: collectListFilters(),
    columns: getSelectedColumns(),
    format: "xlsx",
    requestId: crypto.randomUUID(),
  };

  const job = await request.post("/api/report/export-jobs", payload);
  pollExportJob(job.jobId);
}

async function pollExportJob(jobId) {
  const timer = window.setInterval(async () => {
    const job = await request.get(`/api/report/export-jobs/${jobId}`);

    updateProgress(job.progress);

    if (job.status === "ready") {
      window.clearInterval(timer);
      showDownload(job.downloadUrl, job.expiresAt);
    }

    if (job.status === "failed" || job.status === "expired") {
      window.clearInterval(timer);
      showExportError(job.failReason || "导出任务不可用");
    }
  }, 2000);
}

如果页面关闭后还要继续查看导出结果，可以把最近的 jobId 放到用户偏好或服务端记录里。用户重新打开页面时，前端先查询未完成任务，再决定是否恢复进度条。

总结

前端批量导出接口的关键，不是把下载按钮做得更复杂，而是把职责拆清楚：创建任务负责接收条件，状态接口负责反馈进度和失败原因，下载接口只负责交付已生成文件。这样前端能展示可理解的状态，后端也能用队列、文件存储和过期清理把大文件导出做稳。