Come funziona il middleware in FastAPI?

Question

Accepted Answer

**Middleware** in FastAPI è codice che viene eseguito per **ogni richiesta e risposta** — avvolgendo i tuoi endpoint per gestire aspetti trasversali come logging, timing, CORS e aggiunta di header. FastAPI utilizza il sistema middleware di Starlette (basato su ASGI).

## Scrivere middleware personalizzato

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

Il pattern: il codice prima di `await call_next(request)` viene eseguito in **ingresso** (prima dell'endpoint), `call_next` invoca l'endpoint e il codice dopo viene eseguito in **uscita** (modificando la risposta). Questo avvolge ogni richiesta — qui, aggiungendo un header di timing a tutte le risposte.

## Il flusso di richiesta/risposta

```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 integrato / comune

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

Il middleware viene comunemente aggiunto tramite `add_middleware` — CORS (consenti richieste cross-origin), GZip (comprimi risposte) e trusted-host checks sono built-in tipici.

## Usi comuni del 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 dipendenze

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

## Perché è importante

Il middleware è il meccanismo giusto per **aspetti globali e trasversali** in FastAPI — logica che dovrebbe applicarsi a ogni richiesta e risposta, come logging, timing delle richieste, CORS, compressione e header personalizzati.

Comprendere il middleware è importante per strutturare le applicazioni correttamente: il middleware avvolge tutti gli endpoint (eseguendo prima e dopo, con la possibilità di modificare sia la richiesta che la risposta), rendendolo ideale per il comportamento a livello di app che sarebbe tedioso e soggetto a errori ripetere in ogni endpoint.

Conoscere la distinzione tra **middleware** (globale, a livello di richiesta/risposta grezza) e **dipendenze** (per endpoint, con accesso ai valori analizzati/tipizzati e DI — migliore per autenticazione e validazione) è fondamentale per scegliere lo strumento giusto.

Esigenze comuni come CORS e compressione sono gestite dal middleware integrato, mentre il middleware personalizzato copre logging e instrumentazione — rendendo questa conoscenza pratica e frequentemente utilizzata per costruire API ben strutturate e osservabili.