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 に失われてはいけない作業に依存する一般的な間違いを防ぎ、信頼できるアプリケーションを構築するための重要な実践的知識となります。