BackgroundTasks 如何工作？

Question

Accepted Answer

FastAPI 的 **`BackgroundTasks`** 让您可以在**返回响应后**运行任务——这样客户端可以获得快速的回复，而轻量级的后续工作（发送电子邮件、日志记录、清理）在后台进行。它是内置的，简单易用，适合轻量级任务。

## 使用 BackgroundTasks

```python
from fastapi import BackgroundTasks

def send_email(address: str, message: str):
    # slow-ish work that the client shouldn't wait for
    email_client.send(address, message)

@app.post("/signup")
def signup(user: User, background_tasks: BackgroundTasks):   # inject BackgroundTasks
    save_user(user)
    background_tasks.add_task(send_email, user.email, "Welcome!")   # queue it
    return {"message": "User created"}    # RESPONSE returns NOW; email sends AFTER
```

注入一个 `BackgroundTasks` 参数并调用 `add_task(func, *args)`。FastAPI 先发送响应，然后运行队列中的任务——这样用户不用等待电子邮件的发送。

## 多个任务和与依赖项结合使用

```python
@app.post("/order")
def create_order(order: Order, bg: BackgroundTasks):
    bg.add_task(send_confirmation, order.email)
    bg.add_task(update_analytics, order.id)     # multiple tasks run in order, after the response
    return {"status": "created"}
```

## 关键限制：不适合繁重/关键工作

```text
BackgroundTasks runs IN THE SAME PROCESS as the web server:
  ✗ NO persistence — if the server crashes/restarts, queued tasks are LOST
  ✗ NO retries, scheduling, or distribution
  ✗ Heavy CPU work would still tie up the worker process
→ Good for: quick, non-critical, fire-and-forget tasks (emails, logging, light cleanup)
→ For heavy, critical, retryable, or scheduled jobs → use Celery / ARQ (a real task queue)
```

## 何时使用哪种

```text
BackgroundTasks → simple, lightweight, best-effort work tied to a request (no extra infra)
Celery / ARQ    → durable, retryable, scheduled, distributed jobs (needs a broker/workers)
```

## 为什么这很重要

`BackgroundTasks` 是一个方便的内置工具，用于满足常见的需求——无需让客户端等待就能完成后续工作，如发送欢迎邮件、写日志、轻量级清理——改善用户的响应时间。

理解它对这些日常轻量级的情况很有用，因为它不需要额外的基础设施。

但**最重要的一点**是认识到它的**限制**：由于它在与网络服务器相同的进程中运行，它不提供持久化（任务在崩溃/重启时会丢失）、没有重试、没有调度，也不适合繁重或关键工作。

认识到这个边界——为快速、非关键、一次性任务使用 `BackgroundTasks`，为持久、可重试、计划或繁重的后台作业使用真正的任务队列如 **Celery/ARQ**——这是关键的判断力，可以防止常见的错误做法即依赖 BackgroundTasks 处理不能丢失的工作，这是构建可靠应用程序的重要实践知识。