Como você executa trabalhos em background robustos (Celery/ARQ)?

Question

Accepted Answer

Para **trabalhos em background robustos e duráveis** (além do `BackgroundTasks` leve do FastAPI), você usa uma fila de tarefas real: **Celery** (o padrão estabelecido) ou **ARQ** (uma fila async-nativa moderna). Essas executam trabalho pesado, retentável e agendado em processos worker separados, apoiados por um broker como Redis.

## Por que não apenas BackgroundTasks?

```text
BackgroundTasks runs in the web process → NO persistence (lost on crash), NO retries,
NO scheduling, and heavy work ties up the worker. Fine only for quick fire-and-forget.
For durable/critical/heavy/scheduled jobs → use a real task queue (Celery / ARQ).
```

## Celery — defina e enfileire tarefas

```python
# tasks.py
from celery import Celery
celery_app = Celery("tasks", broker="redis://localhost:6379")

@celery_app.task(bind=True, max_retries=3)
def process_video(self, video_id: int):
    try:
        do_heavy_processing(video_id)        # runs in a WORKER, not the web process
    except Exception as exc:
        raise self.retry(exc=exc, countdown=60)   # automatic retry on failure
```

```python
# in a FastAPI endpoint — QUEUE the task, return immediately
@app.post("/videos/{id}/process")
def process(id: int):
    process_video.delay(id)                  # enqueue → returns at once (doesn't block)
    return {"status": "processing started"}
# run workers separately: celery -A tasks worker
```

O endpoint enfileira o trabalho e responde instantaneamente; um processo **worker** separado o executa com persistência e retentativas.

## ARQ — async-nativo (se adequa ao modelo async do FastAPI)

```python
# ARQ is built on asyncio — a natural fit for async FastAPI codebases
async def process_video(ctx, video_id: int):
    await do_async_processing(video_id)

# enqueue from an endpoint
await redis.enqueue_job("process_video", video_id)
```

ARQ é uma alternativa mais leve e async-first — atraente quando seu codebase já é async.

## O que uma fila de tarefas real fornece

```text
✓ Persistence — jobs survive crashes/restarts (stored in the broker)
✓ Retries with backoff — resilience against transient failures
✓ Scheduling — periodic/cron-like jobs (Celery Beat)
✓ Distribution & scaling — workers scale independently of the web servers
✓ Concurrency & rate limiting, task routing/priorities, result tracking
```

## Por que isso importa

Executar trabalhos em background robustos é essencial para construir aplicações FastAPI de nível produção que lidam com trabalho pesado ou diferido de forma confiável — e entender quando e como usar uma fila de tarefas real é conhecimento importante de nível sênior.

O julgamento central é reconhecer os **limites do `BackgroundTasks`** (sem persistência, retentativas ou agendamento — adequado apenas para trabalho rápido e não-crítico) e recorrer ao **Celery ou ARQ** quando o trabalho deve ser durável, retentável, agendado, pesado ou distribuído (processamento de arquivos/vídeos, envio de emails em massa, sincronização de dados, geração de relatórios).

Essas filas oferecem capacidades críticas de produção: **persistência** (trabalhos sobrevivem a travamentos via o broker, então o trabalho não é perdido), **retentativas automáticas** (resiliência contra falhas transitórias), **agendamento** (trabalhos periódicos) e **escalabilidade independente** de workers a partir de servidores web.

Saber como definir e enfileirar tarefas (`.delay()` do Celery, API async-nativa do ARQ), a arquitetura (broker + workers), e especialmente a **decisão de quando usar uma fila real versus BackgroundTasks**, é valioso para arquitetar aplicações confiáveis que descarregam trabalho pesado sem perdê-lo — um requisito comum e importante que distingue sistemas de produção robustos de sistemas frágeis.