API 异步任务轮询设计指南（免费版）
一、它解决什么问题
导出报表、批量处理、视频转码等操作耗时几十秒到几分钟。若让客户端同步阻塞等待，
连接易超时、服务端占用资源、客户端还可能重复点击。
异步任务模式：提交后立即返回 202 Accepted 和一个 job_id，客户端拿着 job_id
定期轮询状态，完成后取结果——请求短、连接不挂、进度可知。
二、状态机与交互
客户端 POST /tasks ──► 服务端立即返回 202 + {job_id, status_url}
│
▼
客户端轮询 GET /tasks/{job_id}
PENDING ──► RUNNING ──► SUCCEEDED（200 + result）
└─► FAILED（200 + error）
| 状态 | 含义 | HTTP 响应 |
|---|---|---|
| PENDING | 已接收，排队中 | 202/200，body 含 status |
| RUNNING | 处理中 | 200，可带进度 progress |
| SUCCEEDED | 成功完成 | 200，body 含 result |
| FAILED | 处理失败 | 200，body 含 error（是否可重试） |
三、关键设计规则
| 项 | 设计要点 |
|---|---|
| 立即返回 | 提交后返回 202，给 job_id 与 status_url，可带 Retry-After 提示首次轮询时间 |
| 指数退避 | 轮询间隔逐步拉长：1s→2s→4s→8s，并设上限（如 30s），避免高频空轮询压服务端 |
| 总超时 | 客户端设最大等待（max_wait），超时停止并告知用户，不无期限轮询 |
| 幂等键 | 提交时带 Idempotency-Key，网络重试不会重复创建任务 |
| 终态稳定 | SUCCEEDED/FAILED 后状态不再变化，重复查询返回同一结果 |
| 结果获取 | 成功后可直接带 result，或给 result_url 下载 |
四、落地检查清单
- [ ] 提交接口快速返回 202，不阻塞到任务完成
- [ ] 每次轮询返回 job_id、status；RUNNING 可带进度百分比
- [ ] 客户端按指数退避轮询，间隔有上限，不做固定高频轮询
- [ ] 设置总超时，超时停止并提示，不无限等待
- [ ] 提交支持幂等键，重复提交返回同一 job_id 而非新建
- [ ] 终态结果可重复查询；FAILED 说明原因及是否允许重试
- [ ] 服务端任务有自己的执行超时与清理策略，避免任务永久悬挂
- [ ] 轮询响应可带 Retry-After 头，引导客户端下次请求时间
五、判定示例
- 退避序列（base=1、factor=2、上限 10）：1s, 2s, 4s, 8s, 10s, 10s…
- 前 4 次轮询累计等待 1+2+4+8=15s
- max_wait=60s：第 61s 仍未完成 → 判定超时停止
- 任务 PENDING→RUNNING→SUCCEEDED，终态后再查询仍返回同一结果
- 非法参数（base≤0）应兜底为合理默认，不产生负间隔或死循环
六、硬性规则
- 提交与轮询分离，绝不在提交请求里长时间同步等待。
- 轮询必须退避且有上限、有总超时，避免空转压垮服务端。
- 幂等键防止重复任务；终态不可再变、结果可重复读取。
- 本指南为设计方法；需要自动计算退避与超时，请使用专业版。
