¿Cómo funcionan los BackgroundTasks?

Question

Accepted Answer

**`BackgroundTasks`** de FastAPI te permite ejecutar trabajo **después de devolver la respuesta** — para que el cliente reciba una respuesta rápida mientras el trabajo de seguimiento ligero (envío de correo electrónico, registro, limpieza) ocurre en segundo plano. Es integrado y simple, para tareas ligeras.

## Uso de 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
```

Inyecta un parámetro `BackgroundTasks` y llama a `add_task(func, *args)`. FastAPI envía la respuesta primero, luego ejecuta las tareas encoladas — así el usuario no espera el correo electrónico.

## Múltiples tareas y uso con dependencias

```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"}
```

## La limitación crucial: NO es para trabajo pesado/crítico

```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)
```

## Por qué es importante

`BackgroundTasks` es una herramienta integrada conveniente para la necesidad común de hacer trabajo de seguimiento sin hacer que el cliente espere — enviar un correo de bienvenida, escribir un registro, limpieza ligera — mejorando los tiempos de respuesta para el usuario.

Entenderlo es útil para estos casos ligeros cotidianos ya que no requiere infraestructura adicional.

Pero **el punto más importante** es conocer sus **limitaciones**: porque se ejecuta en el mismo proceso que el servidor web, no ofrece persistencia (las tareas se pierden en caída/reinicio), sin reintentos, sin programación, y no es adecuado para trabajo pesado o crítico.

Reconocer este límite — usar `BackgroundTasks` para tareas rápidas, no críticas, "disparar y olvidar", y una cola de tareas real como **Celery/ARQ** para trabajos de fondo duraderos, reintenables, programados o pesados — es el juicio clave que previene el error común de depender de BackgroundTasks para trabajo que no debe perderse, haciendo este conocimiento práctico importante para construir aplicaciones confiables.

## Cuándo usar cuál

```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)
```