用后台任务队列解耦耗时操作：立即返回 Job ID…

当请求需要执行耗时或不稳定的操作（发邮件、生成报表、调用外部服务）时，用任务队列把工作从请求/响应周期中解耦。

适用场景

解决思路

1. 采用任务队列模式：API 接收请求后把任务入队，立即返回一个 job ID，由后台 worker 异步处理。
2. 让 API 立即返回 job ID：为超过几秒的操作创建 Job 记录（状态 PENDING、created_at），入队任务，并返回 job_id、status 和 poll_url 供轮询。
3. 配置 Celery 全局参数：设置 task_time_limit（硬超时，如 3600 秒）、task_soft_time_limit（软超时，如 3000 秒）、task_acks_late=True、task_reject_on_worker_lost=True、worker_prefetch_multiplier=1。
4. 为任务配置重试：使用 @app.task(bind=True, max_retries=3, default_retry_delay=60, autoretry_for=(ConnectionError, TimeoutError))，对瞬时错误用指数退避 self.retry(exc=e, countdown=2 ** self.request.retries * 60)。
5. 区分错误类型：对永久性失败（如 PaymentDeclinedError、校验错误、无效凭证）不重试，直接返回失败结果；只对瞬时错误重试。
6. 让任务幂等：worker 可能因崩溃或超时重试，任务必须可安全重复执行。
7. 实现幂等策略：写前检查状态（check-before-write）、对外部服务调用使用幂等键（如 idempotency_key=f"order-{order_id}"）、使用 upsert（INSERT ... ON CONFLICT UPDATE）、维护 N 小时去重窗口记录已处理 ID。
8. 持久化 Job 状态机：任务状态在 pending → running → succeeded/failed 之间流转，用 JobRepository 的 create 和 update_status 方法写入数据库。
9. 在状态更新时记录时间戳：进入 RUNNING 时写 started_at，进入 SUCCEEDED/FAILED 时写 completed_at，并记录状态变更日志。
10. 处理至少一次投递：多数队列保证 at-least-once，代码必须能处理重复消息。
11. 遵循最佳实践：立即返回、持久化 job 状态、任务幂等、外部调用用幂等键、设置软硬超时、实现 DLQ 捕获永久失败任务、记录状态流转、对瞬时错误指数退避重试、不重试永久失败、监控队列深度并在积压增长时告警。
12. 需要更详细的进阶模式时，阅读 references/details.md。

适用边界 · 注意事项

• 任务能在几秒内同步完成、无需解耦的简单操作。
• 无法容忍重复执行且无法设计幂等性的操作。
• 没有可用的任务队列/worker 基础设施时。