📚 课程目录第2章异步导出任务模型

2. 异步导出任务模型：任务提交、任务状态轮询、结果回调、任务生命周期管理

异步导出任务的核心在于将耗时操作与请求响应解耦，通过任务模型管理整个导出流程。本章详细拆解异步导出任务的四个关键阶段：任务提交、任务状态轮询、结果回调以及任务生命周期管理，为后续网关超时重试与降级设计奠定基础。

设计原则：异步导出任务模型必须保证幂等性、可追踪性以及状态一致性，避免因超时重试导致重复导出或数据不一致。

2.1 任务提交

任务提交是异步导出的入口，客户端发起导出请求后，网关或后端服务立即返回一个全局唯一的任务ID，并将任务信息持久化到存储层。

提交参数	说明	示例
`task_id`	全局唯一任务标识，由网关生成	`exp-20250321-abc123`
`export_type`	导出类型，如订单、用户、报表	`order_export`
`filters`	导出筛选条件，JSON格式	`{"date_from":"2025-01-01"}`
`callback_url`	异步回调地址，可选	`https://api.example.com/callback`
`timeout_sec`	任务超时时间，默认300秒	`600`

提交成功后，服务端将任务状态置为 PENDING，并放入消息队列等待异步执行。客户端收到 202 Accepted 响应，携带 task_id 用于后续轮询。

// 任务提交响应示例
HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "exp-20250321-abc123",
    "status": "PENDING",
    "estimated_completion_sec": 120
  }
}

2.2 任务状态轮询

客户端通过 task_id 定期轮询任务状态，获取当前进度或最终结果。轮询接口需支持幂等查询，避免重复消费。

  轮询策略建议：
  指数退避：初始间隔1秒，最大间隔30秒，减少无效请求。
状态缓存：网关层对 COMPLETED / FAILED 状态做短时缓存（如5秒），避免穿透到后端。
轮询超时：客户端设置最大轮询时长（如5分钟），超时后进入降级流程。

任务状态定义如下：

状态	含义	可轮询	可重试
`PENDING`	任务已提交，等待执行	是	否
`RUNNING`	任务正在执行中	是	否
`COMPLETED`	任务执行成功，结果可下载	是	否
`FAILED`	任务执行失败，含错误信息	是	是（需判断失败原因）
`TIMEOUT`	任务超时未完成	否	是（触发降级重试）
`CANCELLED`	任务被手动取消	否	否

2.3 结果回调

当任务状态变为 COMPLETED 或 FAILED 时，后端服务通过预先注册的 callback_url 主动通知客户端，避免客户端持续轮询。回调机制是降低网关与客户端压力的关键手段。

回调可靠性设计：

重试机制：回调失败后，按指数退避重试最多3次，间隔分别为1s、4s、16s。
幂等性：回调请求携带 task_id 和 callback_seq（递增序列号），客户端需去重。
超时降级：若回调多次失败，转为客户端主动轮询或人工介入。

// 回调请求示例（POST）
POST /callback HTTP/1.1
Content-Type: application/json

{
  "task_id": "exp-20250321-abc123",
  "status": "COMPLETED",
  "download_url": "https://storage.example.com/exports/exp-20250321-abc123.csv",
  "expire_at": "2025-03-22T00:00:00Z",
  "callback_seq": 1
}

2.4 任务生命周期管理

任务从创建到最终销毁的完整生命周期，需要精细化管理，确保资源可回收、状态可追溯。

生命周期管理的关键策略：

阶段	管理动作	说明
创建	生成 task_id，持久化任务元数据	写入任务表，状态 PENDING
执行	更新状态为 RUNNING，记录开始时间	支持进度百分比更新
完成/失败	更新最终状态，存储结果路径或错误信息	触发回调通知
超时	强制置为 TIMEOUT，释放工作线程	触发网关重试降级流程
取消	标记 CANCELLED，中断执行线程	需保证中断安全
过期	清理任务记录与临时文件	TTL 通常为 24-72 小时

  超时处理要点：当任务达到预设超时时间（如300秒）仍未完成，服务端应主动将状态置为 TIMEOUT，并释放数据库连接、线程池等资源。此时网关应触发重试降级策略（详见后续章节），避免客户端无限等待。

通过以上四个阶段的标准化设计，异步导出任务模型具备了可观测、可控制、可恢复的特性，为网关层实现超时重试与降级提供了清晰的状态边界和操作接口。