Cum funcționează middleware-ul în FastAPI?

Question

Accepted Answer

**Middleware** în FastAPI este cod care se execută pentru **fiecare cerere și răspuns** — înfășurând punctele finale ale dvs. pentru a gestiona probleme transversale, cum ar fi logging, cronometrare, CORS și adăugarea de anteturi. FastAPI utilizează sistemul de middleware al Starlette (este bazat pe ASGI).

## Scrierea de middleware personalizat

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

Schema: codul înaintea `await call_next(request)` se execută **pe drumul înainte** (înaintea punctului final), `call_next` invocă punctul final, iar codul după se execută **pe drumul înapoi** (modificând răspunsul). Aceasta înfășoară fiecare cerere — aici, adăugând o antetă de cronometrare la toate răspunsurile.

## Fluxul cererilor/răspunsurilor

```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 încorporat / obișnuit

```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 este adăugat de obicei prin `add_middleware` — CORS (permite cererile între origini), GZip (comprima răspunsurile) și verificările gazdelor de încredere sunt middleware-ul încorporat tipic.

## Utilizări obișnuite ale middleware-ului

```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 dependențe

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

## De ce contează

Middleware este mecanismul potrivit pentru **problemele globale și transversale** în FastAPI — logica care ar trebui aplicată pentru fiecare cerere și răspuns, cum ar fi logging, cronometrarea cererii, CORS, compresie și antete personalizate.

A-l înțelege este important pentru structurarea corectă a aplicațiilor: middleware-ul înfășoară toate punctele finale (executând înainte și după, cu capacitatea de a modifica atât cererea, cât și răspunsul), făcând-o ideală pentru comportamentul la nivelul aplicației care ar fi obositor și predispus la erori repetad în fiecare punct final.

A cunoaște distinția dintre **middleware** (global, nivel brut de cerere/răspuns) și **dependențe** (per-punct final, cu acces la valori analizate/tipizate și DI — mai bune pentru autentificare și validare) este esențial pentru a alege instrumentul potrivit.

Nevoile comune, cum ar fi CORS și compresie, sunt gestionate de middleware-ul încorporat, în timp ce middleware-ul personalizat acoperă logging și instrumentare — făcând acestei cunoștințe practice și frecvent utilizate pentru construirea API-urilor bine structurate și observabile.