用 202 Accepted 与 303 See Other 实现异步导出任务接口

举报
yd_250998817 发表于 2026/11/16 08:50:40 2026/11/16
【摘要】 异步导出接口通常创建即返回、客户端轮询。本文用 202 Accepted 配合 Location 与 Retry-After 表示任务已受理,完成后用 303 See Other 把状态查询重定向到下载地址,并给出 Express 最小实现与 curl 轮询验证步骤,说明退避、持久化与鉴权边界。

问题场景

报表、日志、账单这类数据导出往往耗时数秒到数分钟。如果在 POST /exports 里同步生成文件再返回,网关和客户端都可能超时,连接被占用,用户体验也差。更常见的做法是「受理—轮询—取结果」三段式:

  1. 客户端 POST 提交导出请求,服务端只创建任务,立即返回任务状态地址;
  2. 客户端按建议间隔轮询 GET 任务状态;
  3. 任务完成后,服务端用重定向把客户端引到真正的下载地址。

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)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。