1. 异步导出任务概述
1.1 什么是异步导出任务
异步导出任务是指客户端发起导出请求后，服务端立即返回一个任务标识（Task ID），并在后台独立线程或队列中执行数据导出、文件生成等耗时操作，客户端通过轮询或回调机制获取最终结果的处理模式。与同步导出不同，异步导出不要求客户端保持长连接等待响应，适用于数据量大、处理时间长的场景。
核心特征：请求与执行分离、非阻塞、可追踪进度、支持失败重试。
1.2 适用场景
异步导出任务主要解决以下三类典型问题：
- 大数据量导出：单次导出记录数超过 10 万行，或数据体积超过 100 MB，同步接口容易触发网关超时（通常 30s～60s）。
- 耗时操作：涉及跨库查询、复杂聚合计算、文件压缩或加密，处理时间超过 5 秒。
- 资源隔离需求：导出操作需要与核心业务接口分离，避免占用 Web 容器线程池导致接口雪崩。
| 场景 | 数据量 | 典型耗时 | 推荐模式 |
|---|---|---|---|
| 报表导出（月/季度） | 50 万～200 万行 | 30s～5min | 异步 |
| 日志导出（单日） | 10 万～50 万行 | 5s～30s | 异步 |
| 用户列表导出（分页） | 1 万行以内 | < 3s | 同步 |
| 实时交易流水查询 | 100 条以内 | < 1s | 同步 |
1.3 异步导出 vs 同步导出
两种模式在接口设计、用户体验、容错策略上存在显著差异，下表从 7 个关键维度进行对比：
| 对比维度 | 同步导出 | 异步导出 |
|---|---|---|
| 响应方式 | 直接返回文件流或数据体 | 返回任务 ID + 状态 URL |
| 连接时长 | 请求持续到导出完成 | 请求立即返回，连接释放 |
| 超时风险 | 高（网关/负载均衡器超时） | 低（仅任务状态查询短连接） |
| 错误处理 | 直接返回 HTTP 错误码 | 任务状态标记失败，可查询原因 |
| 重试机制 | 客户端重新发起完整请求 | 支持断点续传或仅重试失败步骤 |
| 资源消耗 | 占用 Web 容器线程 | 后台队列/线程池执行 |
| 用户体验 | 页面等待，可能白屏 | 可展示进度条，支持后台下载 |
常见误区：并非所有导出都适合异步。当数据量小（< 1 万行）且处理时间短（< 3s）时，同步导出更简单、延迟更低。异步会引入额外的任务存储、轮询开销和状态管理复杂度。
1.4 异步导出任务生命周期
一个标准的异步导出任务经历以下状态流转：
- PENDING（待处理）：任务已创建，等待调度。
- RUNNING（执行中）：后台线程正在查询数据、生成文件。
- SUCCESS（成功）：文件已生成，提供下载链接。
- FAILED（失败）：执行过程中发生异常，记录错误信息。
- CANCELLED（取消）：用户主动终止任务。
设计建议：在 OpenAPI 参数校验层，建议对异步导出接口的
export_type、date_range、format 等参数做前置校验，避免无效参数进入队列浪费资源。校验失败时返回 422 状态码 + 结构化错误体，而非直接丢弃任务。