用 202 Accepted 与 303 See Other 实现异步导出任务接口
【摘要】 异步导出接口通常创建即返回、客户端轮询。本文用 202 Accepted 配合 Location 与 Retry-After 表示任务已受理,完成后用 303 See Other 把状态查询重定向到下载地址,并给出 Express 最小实现与 curl 轮询验证步骤,说明退避、持久化与鉴权边界。
问题场景
报表、日志、账单这类数据导出往往耗时数秒到数分钟。如果在 POST /exports 里同步生成文件再返回,网关和客户端都可能超时,连接被占用,用户体验也差。更常见的做法是「受理—轮询—取结果」三段式:
- 客户端
POST提交导出请求,服务端只创建任务,立即返回任务状态地址; - 客户端按建议间隔轮询
GET任务状态; - 任务完成后,服务端用重定向把客户端引到真正的下载地址。
HTTP 语义里正好有三件工具对应这三步:202 Accepted、Location + Retry-After、303 See Other。
语义设计
| 步骤 | 方法/路径 | 状态码 | 关键响应头 |
|---|---|---|---|
| 创建任务 | POST /exports |
202 Accepted |
Location: /exports/{id}、Retry-After: 2 |
| 查询状态(未完成) | GET /exports/{id} |
200 OK |
Retry-After: 2、Cache-Control: no-store |
| 查询状态(已完成) | GET /exports/{id} |
303 See Other |
Location: /exports/{id}/file |
| 下载结果 | GET /exports/{id}/file |
200 OK |
Content-Disposition: attachment |
几个容易踩的点:
202的意思是「已受理、尚未完成」,响应体应给出任务标识和状态地址,而不是结果本身。Location在202里指向状态资源,不是最终文件。Retry-After可以是秒数,也可以是 HTTP-date。语义上它最标准的用法是配合503/429,在202上它是一种被广泛接受的约定,客户端不应强制依赖。- 用
303而不是302:303明确要求把后续请求改成GET目标 URI,语义无歧义。
Express 最小实现
以下代码用内存 Map 保存任务,只为演示协议流转,生产环境需替换为 Redis 或数据库。
// server.js
const express = require('express');
const crypto = require('node:crypto');
const app = express();
app.use(express.json());
const TASKS = new Map(); // id -> { status, createdAt, fileName, body }
const RETRY_AFTER = 2; // 秒
const FAKE_WORK_MS = 2000; // 模拟导出耗时
function sleep(ms) {
return new Promise((r) => setTimeout(r, ms));
}
// 1) 创建任务:202 + Location + Retry-After
app.post('/exports', async (req, res) => {
const id = crypto.randomUUID();
TASKS.set(id, { status: 'pending', createdAt: new Date().toISOString() });
// 后台执行,不阻塞响应
(async () => {
await sleep(FAKE_WORK_MS);
const task = TASKS.get(id);
if (!task || task.status !== 'pending') return; // 已被取消或清理
task.status = 'done';
task.fileName = `export-${id}.csv`;
task.body = 'id,name\n1,示例A\n2,示例B\n';
task.finishedAt = new Date().toISOString();
})();
res
.status(202)
.location(`/exports/${id}`)
.set('Retry-After', String(RETRY_AFTER))
.set('Cache-Control', 'no-store')
.json({ id, status: 'pending', statusUrl: `/exports/${id}` });
});
// 2) 查询状态:未完成 200,已完成 303
app.get('/exports/:id', (req, res) => {
const { id } = req.params;
const task = TASKS.get(id);
if (!task) return res.status(404).json({ error: 'task_not_found' });
if (task.status === 'done') {
return res
.status(303)
.location(`/exports/${id}/file`)
.set('Cache-Control', 'no-store')
.end();
}
res
.status(200)
.set('Retry-After', String(RETRY_AFTER))
.set('Cache-Control', 'no-store')
.json({ id, status: task.status, createdAt: task.createdAt });
});
// 3) 下载结果
app.get('/exports/:id/file', (req, res) => {
const { id } = req.params;
const task = TASKS.get(id);
if (!task) return res.status(404).json({ error: 'task_not_found' });
if (task.status !== 'done') return res.status(409).json({ error: 'task_not_ready' });
res
.type('text/csv; charset=utf-8')
.set('Content-Disposition', `attachment; filename="${task.fileName}"`)
.send('\uFEFF' + task.body); // BOM 便于表格软件识别 UTF-8
});
app.listen(3000, () => console.log('listening on http://localhost:3000'));
运行方法
mkdir async-export && cd async-export
npm init -y
npm install express@4
# 将上面的代码保存为 server.js
node server.js
服务监听 http://localhost:3000。express@4 只是写作时的可用版本,实际项目请按官方发布说明选择版本。
curl 轮询验证
第一步,创建任务并查看响应头:
curl -i -X POST http://localhost:3000/exports
预期看到 HTTP/1.1 202 Accepted、Location: /exports/<id>、Retry-After: 2。把返回的任务 ID 记到变量里:
ID=<粘贴创建响应中的 id>
第二步,轮询状态直到出现 303:
for i in $(seq 1 10); do
code=$(curl -s -o /dev/null -w '%{http_code}' -D /tmp/h.txt "http://localhost:3000/exports/$ID")
echo "第 $i 次: $code"
grep -i '^location:' /tmp/h.txt || true
[ "$code" = "303" ] && break
sleep 2
done
前几次应输出 200,约 2 秒后变为 303,并打印 Location: /exports/<id>/file。
第三步,让 curl 自动跟随重定向取文件:
curl -L -o export.csv "http://localhost:3000/exports/$ID"
head -3 export.csv
-L 会跟随 303 并在新请求中改用 GET,最终把 CSV 写入本地文件。也可以直接访问 http://localhost:3000/exports/$ID/file 验证下载接口本身。
边界与限制
- 状态易失:示例用内存
Map,进程重启任务即丢失。多实例部署必须把任务状态放到共享存储,并用唯一 ID 做幂等键。 - 重复创建:客户端超时重试会造出多个任务。建议支持
Idempotency-Key请求头,相同键返回同一个任务地址。 - 轮询风暴:固定 2 秒轮询在任务量大的时候会压垮状态接口,客户端应做指数退避并设置上限,服务端可对高频请求返回
429+Retry-After。 Retry-After不是承诺:它只是建议值,客户端不能假定「等满 2 秒就一定完成」,必须持续检查状态码。303的适用范围:303只表示「去别处用 GET 取结果」。如果任务还在跑就返回303,客户端会拿到一个 409 或空文件,因此状态判断必须严格。- 下载地址鉴权:文件 URL 往往被直接分享,应带签名与过期时间,或要求携带令牌访问,不要依赖「猜不到 ID」这种隐蔽式安全。
- 缓存干扰:状态响应务必带
Cache-Control: no-store,否则中间代理可能返回过期的200。 - 大文件:示例一次性把内容放进内存,真实场景应流式输出或落对象存储后返回预签名地址,避免内存溢出。
- 清理与超时:需要为任务设置 TTL,长时间未完成的任务应标记失败,并提供显式的取消接口,否则状态表会无限增长。
【版权声明】本文为华为云社区用户原创内容,未经允许不得转载,如需转载请自行联系原作者进行授权。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)