Miten middleware toimii FastAPI:ssä?

Question

Accepted Answer

**Middleware** FastAPI:ssä on koodi, joka suoritetaan **jokaiselle request:ille ja response:ille** — se kääritään endpointien ympärille käsitelläkseen poikittaisia huolenaiheita, kuten logging, timing, CORS ja headereiden lisäämistä. FastAPI käyttää Starletteen middleware-järjestelmää (se on ASGI-pohjainen).

## Mukautetun middlewaren kirjoittaminen

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

Kuvio: koodi ennen `await call_next(request)`-kutsua suoritetaan matkalla **sisään** (ennen endpointia), `call_next` kutsuu endpointin ja koodi sen jälkeen suoritetaan matkalla **ulos** (muokkaamalla responsea). Tämä kääritään jokaisen requestin ympärille — tässä lisätään timing-header kaikkiin responseihin.

## Request/response-virta

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

## Sisäänrakennettu / yleinen 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 lisätään yleensä `add_middleware`-funktion kautta — CORS (salli cross-origin-requestit), GZip (pakkaa responseet) ja luotetun hostin tarkistukset ovat tyypillisiä sisäänrakennettuja.

## Middlewaren yleiset käyttökohteet

```text
✓ Logging / request timing / metrics
✓ CORS (cross-origin request handling)
✓ Adding security or custom headers
✓ Response compression (GZip)
✓ Request ID / correlation ID injection
```

## Middleware vai riippuvuudet

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

## Miksi se on tärkeää

Middleware on oikea mekanismi **globaaleille, poikittaisille huolenaiheille** FastAPI:ssä — logiikka, jota tulisi soveltaa jokaiselle request:ille ja response:lle, kuten logging, requestin timing, CORS, pakkaus ja mukautetut headerit.

Sen ymmärtäminen on tärkeää sovellusten oikealle rakenteelle: middleware kääritään kaikkien endpointien ympärille (se suoritetaan ennen ja jälkeen, kyvyllä muokata sekä requestia että responsea), mikä tekee siitä ihanteellisen koko sovellukseen liittyvälle käyttäytymiselle, jota olisi väsyneyttävää ja virheille altista toistaa jokaisessa endpointissa.

**Middlewaren** (globaali, raa request/response-taso) ja **riippuvuuksien** (per-endpoint, jolla on pääsy jäsennettyihin/tyypitettyihin arvoihin ja DI:hin — parempi autentikoinnille ja validoinnille) välisen eron tunteminen on avain oikean työkalun valintaan.

Yleiset tarpeet, kuten CORS ja pakkaus, käsitellään sisäänrakennetulla middlewarella, kun taas mukautettu middleware kattaa loggingiin ja instrumentointiin — joten tämä on käytännön, usein käytetty tieto hyvin jäsenneltyjen, havaittavissa olevien sovellusliittymien rakentamiselle.