Jak middleware funguje v FastAPI?

Question

Accepted Answer

**Middleware** v FastAPI je kód, který se spustí pro **každý request a response** — zabaluje vaše endpoints, aby se zabýval cross-cutting concerns jako logging, měření času, CORS a přidávání headerů. FastAPI používá middleware systém Starlette (je založen na ASGI).

## Psaní vlastního 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
```

Vzor: kód před `await call_next(request)` se spustí na cestě **dovnitř** (před endpointem), `call_next` vyvolá endpoint a kód po něm se spustí na cestě **ven** (úprava response). Toto zabaluje každý request — zde se přidává timing header ke všem responses.

## Tok request/response

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

## Vestavěné / běžné 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 se běžně přidává prostřednictvím `add_middleware` — CORS (umožnění cross-origin requestů), GZip (komprese responses) a kontrola trusted-host jsou typickévestavěné.

## Běžné použití 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 versus dependencies

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

## Proč je to důležité

Middleware je správným mechanismem pro **globální, cross-cutting concerns** v FastAPI — logiku, která by měla platit pro každý request a response, jako logging, měření času requestu, CORS, kompresi a vlastní headery.

Její pochopení je důležité pro správné strukturování aplikací: middleware zabaluje všechny endpointy (běží před a po, s možností upravit request i response), takže je ideální pro chování v rámci celé aplikace, které by bylo zdlouhavé a náchylné chybám opakovat v každém endpointu.

Znalost rozlišení mezi **middleware** (globální, hrubá úroveň request/response) a **dependencies** (pro jednotlivé endpointy, s přístupem k analyzovaným/typovaným hodnotám a DI — lepší pro autentizaci a validaci) je klíčem k výběru správného nástroje.

Běžné potřeby jako CORS a komprese jsou řešeny vestavěným middleware, zatímco vlastní middleware pokrývá logging a instrumentaci — což činí tuto praktickou, často používanou znalostí pro budování dobře strukturovaných, pozorovatelných API.