SuperAPI AI 工具集

python-background-jobs

编程与开发

查看项目

更新于 10-16 07:31

技能介绍

用途

Python 后台任务与任务队列技能用于将长时间运行或不可靠的工作从请求/响应周期中解耦。应用可以立即向用户返回响应,同时由后台工作进程异步处理繁重任务。

适用场景

  • 处理耗时超过数秒的任务
  • 发送邮件、通知或 webhook
  • 生成报告或导出数据
  • 处理上传或媒体转换
  • 集成不可靠的外部服务
  • 构建事件驱动架构

核心概念

  1. 任务队列模式:API 接受请求后入队一个作业,立即返回作业 ID;工作进程异步处理作业。
  2. 幂等性:任务失败时可能被重试,需要设计为可安全重复执行。
  3. 作业状态机:作业在状态间转换:pending → running → succeeded/failed。
  4. 至少一次投递:多数队列保证至少一次投递,代码必须处理重复投递。

快速上手

文档以广泛采用的 Celery 为例,RQ、Dramatiq 以及云原生方案(AWS SQS、GCP Tasks)同样是有效选择。示例代码:

from celery import Celery

app = Celery("tasks", broker="redis://localhost:6379")

@app.task
def send_email(to: str, subject: str, body: str) -> None:
    # This runs in a background worker
    email_client.send(to, subject, body)

# In your API handler
send_email.delay("user@example.com", "Welcome!", "Thanks for signing up")

基本模式

模式 1:立即返回作业 ID

对于超过数秒的操作,返回作业 ID 并异步处理。示例中定义了 JobStatus 枚举(PENDING、RUNNING、SUCCEEDED、FAILED)和 Job 数据类,记录 id、status、created_at、started_at、completed_at、result、error。API 端点 start_export 生成 job_id、持久化作业记录、入队后台任务,并立即返回 job_id、状态与轮询地址。

模式 2:Celery 任务配置

为 Celery 任务配置合理的重试与超时设置,包括全局配置项 task_time_limit(硬限制 1 小时)、task_soft_time_limit(软限制 50 分钟)、task_acks_late(完成后确认)、task_reject_on_worker_lost、worker_prefetch_multiplier。示例任务 process_payment 使用 bind=True、max_retries=3、default_retry_delay=60、autoretry_for=(ConnectionError, TimeoutError):永久性失败(如 PaymentDeclinedError)不重试,瞬时错误按指数退避重试。

模式 3:使任务幂等

工作进程可能因崩溃或超时而重试,需要设计为可安全重复执行。示例任务 process_order 先检查订单是否已完成,若已处理则直接返回;调用支付提供方时传入幂等键 f"order-{order_id}",处理完成后更新订单状态。

幂等策略:写前检查、幂等键(与外部服务使用唯一令牌)、upsert 模式(INSERT ... ON CONFLICT UPDATE)、去重窗口(记录已处理 ID 若干小时)。

模式 4:作业状态管理

持久化作业状态转换以便可见性和调试。示例 JobRepository 提供 create 方法插入作业记录,update_status 方法更新状态并在进入 RUNNING 时记录 started_at,在 SUCCEEDED/FAILED 时记录 completed_at,同时记录日志。

进阶模式

进阶模式(从 ## Advanced Patterns 开始)位于 references/details.md,当上方导航摘要不足时阅读该文件。

最佳实践总结

  • 立即返回:不要阻塞请求去执行长操作
  • 持久化作业状态:支持状态轮询与调试
  • 使任务幂等:任何失败都可安全重试
  • 使用幂等键:用于外部服务调用
  • 设置超时:同时使用软限制与硬限制
  • 实现死信队列(DLQ):捕获永久失败的任务
  • 记录状态转换:跟踪作业状态变化
  • 合理重试:瞬时错误使用指数退避
  • 不重试永久性失败:如校验错误、无效凭证
  • 监控队列深度:积压增长时告警

限制

本文档未提供具体收费、价格、平台支持范围或性能效果数据。示例以 Celery 为主,其他队列方案的具体用法暂未提供。更多代码细节见 references/details.md。