Comment fonctionne le middleware dans FastAPI ?

Question

Accepted Answer

**Middleware** dans FastAPI est du code qui s'exécute pour **chaque requête et réponse** — enveloppant vos endpoints pour gérer les préoccupations transversales comme la journalisation, le minutage, CORS et l'ajout d'en-têtes. FastAPI utilise le système de middleware de Starlette (basé sur ASGI).

## Écrire un middleware personnalisé

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

Le modèle : le code avant `await call_next(request)` s'exécute à l'entrée **in** (avant l'endpoint), `call_next` invoque l'endpoint, et le code après s'exécute à la sortie **out** (en modifiant la réponse). Cela enveloppe chaque requête — ici, en ajoutant un en-tête de minutage à toutes les réponses.

## Le flux requête/réponse

```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 intégré / courant

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

Le middleware est généralement ajouté via `add_middleware` — CORS (permettre les requêtes cross-origin), GZip (compresser les réponses) et les vérifications de host de confiance sont des éléments intégrés typiques.

## Cas d'usage courants du 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 dépendances

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

## Pourquoi c'est important

Le middleware est le mécanisme approprié pour les **préoccupations globales et transversales** dans FastAPI — une logique qui devrait s'appliquer à chaque requête et réponse, comme la journalisation, le minutage des requêtes, CORS, la compression et les en-têtes personnalisés.

Le comprendre est important pour structurer correctement les applications : le middleware enveloppe tous les endpoints (s'exécutant avant et après, avec la capacité de modifier à la fois la requête et la réponse), ce qui le rend idéal pour le comportement à l'échelle de l'application qui serait fastidieux et sujet aux erreurs de répéter dans chaque endpoint.

Connaître la distinction entre **middleware** (global, au niveau brut requête/réponse) et **dépendances** (par endpoint, avec accès aux valeurs analysées/typées et à l'injection de dépendances — meilleur pour l'auth et la validation) est clé pour choisir le bon outil.

Les besoins courants comme CORS et la compression sont gérés par le middleware intégré, tandis que le middleware personnalisé couvre la journalisation et l'instrumentation — ce qui rend ces connaissances pratiques et fréquemment utilisées pour construire des API bien structurées et observables.