Como funciona o middleware no FastAPI?

Question

Accepted Answer

**Middleware** no FastAPI é código que é executado para **cada requisição e resposta** — envolvendo seus endpoints para lidar com preocupações transversais, como registro, cronometragem, CORS e adição de cabeçalhos. FastAPI usa o sistema de middleware do Starlette (é baseado em ASGI).

## Escrevendo middleware personalizado

```python
import time

@app.middleware("http")
async def add_timing(request: Request, call_next):
    start = time.time()
    response = await call_next(request)        # call the endpoint (and any inner middleware)
    response.headers["X-Process-Time"] = str(time.time() - start)   # modify the response
    return response
```

O padrão: o código antes de `await call_next(request)` é executado **na entrada** (antes do endpoint), `call_next` invoca o endpoint, e o código depois é executado **na saída** (modificando a resposta). Isso envolve cada requisição — aqui, adicionando um cabeçalho de cronometragem a todas as respostas.

## O fluxo de requisição/resposta

```text
Request  → MW1 → MW2 → endpoint
Response ← MW1 ← MW2 ← endpoint
Middleware wraps the endpoint; runs in order on the way in, reverse on the way out.
```

## Middleware integrado / comum

```python
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware

app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"], ...)  # CORS
app.add_middleware(GZipMiddleware, minimum_size=1000)                               # compression
```

Middleware é comumente adicionado via `add_middleware` — CORS (permitir requisições entre origens), GZip (comprimir respostas) e verificações de host confiável são middleware integrado típico.

## Usos comuns de middleware

```text
✓ Logging / request timing / metrics
✓ CORS (cross-origin request handling)
✓ Adding security or custom headers
✓ Response compression (GZip)
✓ Request ID / correlation ID injection
```

## Middleware vs dependências

```text
Middleware   → runs for ALL requests; works at the raw request/response level (headers,
               timing, the whole response). Best for truly global concerns.
Dependencies → per-endpoint (or grouped) logic with access to parsed params, DI, and
               typed values. Best for auth, validation, shared parameters.
→ Use middleware for global cross-cutting concerns; dependencies for endpoint logic.
```

## Por que isso importa

Middleware é o mecanismo correto para **preocupações globais e transversais** no FastAPI — lógica que deve ser aplicada a cada requisição e resposta, como registro, cronometragem de requisição, CORS, compressão e cabeçalhos personalizados.

Entender isso é importante para estruturar as aplicações corretamente: o middleware envolve todos os endpoints (executando antes e depois, com a capacidade de modificar requisição e resposta), tornando-o ideal para o comportamento em toda a aplicação que seria tedioso e propenso a erros repetir em cada endpoint.

Conhecer a distinção entre **middleware** (global, nível bruto de requisição/resposta) e **dependências** (por-endpoint, com acesso a valores analisados/digitados e DI — melhor para autenticação e validação) é fundamental para escolher a ferramenta correta.

Necessidades comuns como CORS e compressão são tratadas pelo middleware integrado, enquanto o middleware personalizado cobre registro e instrumentação — tornando esse conhecimento prático e frequentemente usado para construir APIs bem estruturadas e observáveis.