Jak działa middleware w FastAPI?

Question

Accepted Answer

**Middleware** w FastAPI to kod, który uruchamia się dla **każdego żądania i odpowiedzi** — opakowując Twoje punkty końcowe, aby obsługiwać zagadnienia krzyżowe, takie jak logowanie, mierzenie czasu, CORS i dodawanie nagłówków. FastAPI korzysta z systemu middleware Starlette'a (oparty na ASGI).

## Pisanie niestandardowego middleware

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

Wzór: kod przed `await call_next(request)` uruchamia się **na wejściu** (przed punktem końcowym), `call_next` wywoła punkt końcowy, a kod po **na wyjściu** (modyfikując odpowiedź). To opakowuje każde żądanie — tutaj dodając nagłówek czasu do wszystkich odpowiedzi.

## Przepływ żądania/odpowiedzi

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

## Wbudowane / powszechne middleware

```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 zwykle dodaje się przez `add_middleware` — CORS (zezwalaj na żądania między źródłami), GZip (kompresuj odpowiedzi) i sprawdzenia zaufanych hostów to typowe wbudowane rozwiązania.

## Powszechne zastosowania 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 kontra zależności

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

## Dlaczego to ważne

Middleware to właściwy mechanizm dla **globalnych, krzyżowych zagadnień** w FastAPI — logiki, która powinna być stosowana do każdego żądania i odpowiedzi, takie jak logowanie, pomiar czasu żądania, CORS, kompresja i niestandardowe nagłówki.

Zrozumienie go jest ważne dla prawidłowego strukturowania aplikacji: middleware opakowuje wszystkie punkty końcowe (uruchamiając się przed i po, z możliwością modyfikacji zarówno żądania, jak i odpowiedzi), co czyni go idealnym dla zachowań całej aplikacji, które byłoby żmudne i podatne na błędy powtarzać w każdym punkcie końcowym.

Znajomość rozróżnienia między **middleware** (globalnym, na poziomie surowego żądania/odpowiedzi) i **zależnościami** (per-punkt końcowy, z dostępem do przeanalizowanych/wpisanych wartości i DI — lepsze dla uwierzytelniania i walidacji) jest kluczowa do wyboru odpowiedniego narzędzia.

Powszechne potrzeby, takie jak CORS i kompresja, są obsługiwane przez wbudowane middleware, podczas gdy niestandardowe middleware obejmuje logowanie i instrumentację — czyniąc tę praktyczną, często używaną wiedzę dla budowania dobrze ustrukturyzowanych, obserwowalnych API.