Como os BackgroundTasks funcionam?

Question

Accepted Answer

O **`BackgroundTasks`** do FastAPI permite executar trabalho **após retornar a resposta** — então o cliente recebe uma resposta rápida enquanto trabalhos de acompanhamento leves (enviar e-mail, logging, limpeza) acontecem em segundo plano. É integrado e simples, para tarefas leves.

## Usando 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
```

Injete um parâmetro `BackgroundTasks` e chame `add_task(func, *args)`. FastAPI envia a resposta primeiro e, em seguida, executa as tarefas enfileiradas — então o usuário não fica esperando pelo e-mail.

## Múltiplas tarefas e uso com dependências

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

## A limitação crucial: NÃO é para trabalho 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)
```

## Quando usar qual

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

## Por que isso importa

`BackgroundTasks` é uma ferramenta integrada conveniente para a necessidade comum de fazer trabalho de acompanhamento sem fazer o cliente esperar — enviar um e-mail de boas-vindas, escrever um log, limpeza leve — melhorando os tempos de resposta para o usuário.

Compreendê-lo é útil para esses casos leves do dia a dia, pois não requer infraestrutura extra.

Mas o **ponto mais importante** é conhecer suas **limitações**: porque é executado no mesmo processo do servidor web, não oferece persistência (as tarefas são perdidas em crashes/reinicializações), sem retentativas, sem agendamento e não é adequado para trabalho pesado ou crítico.

Reconhecer esse limite — usando `BackgroundTasks` para tarefas rápidas, não críticas, disparar-e-esquecer, e uma fila de tarefas real como **Celery/ARQ** para trabalhos de fundo duráveis, retentáveis, agendados ou pesados — é o julgamento-chave que evita o erro comum de confiar em BackgroundTasks para trabalho que não deve ser perdido, tornando esse conhecimento prático importante para construir aplicações confiáveis.