FastAPI'da middleware nasıl çalışır?

Question

Accepted Answer

**Middleware**, FastAPI'da **her istek ve yanıt** için çalışan kod — uç noktalarınızı sarmalayarak logging, zamanlama, CORS ve başlık ekleme gibi genel sorunları ele alır. FastAPI, Starlette'in middleware sistemini kullanır (ASGI tabanlıdır).

## Özel middleware yazma

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

Desen: `await call_next(request)` öncesindeki kod **giriş** yolunda çalışır (uç noktadan önce), `call_next` uç noktayı çağırır ve sonrası kod **çıkış** yolunda çalışır (yanıtı değiştirir). Bu her isteği sarmaladığında — burada, tüm yanıtlara zamanlama başlığı eklenir.

## İstek/yanıt akışı

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

## Yerleşik / yaygı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 genellikle `add_middleware` aracılığıyla eklenir — CORS (orijinler arası isteklere izin ver), GZip (yanıtları sıkıştır) ve güvenilen host kontrolleri tipik yerleşik örneklerdir.

## Middleware'in yaygın kullanımları

```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 bağımlılıklar

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

## Neden önemli

Middleware, FastAPI'da **global, genel sorunlar** için doğru mekanizmadır — logging, istek zamanlaması, CORS, sıkıştırma ve özel başlıklar gibi her isteğe ve yanıta uygulanması gereken mantık.

Bunu anlamak, uygulamaları doğru şekilde yapılandırmak için önemlidir: middleware tüm uç noktaları sarmaladığında (önce ve sonra çalışarak, hem isteği hem de yanıtı değiştirme yeteneğine sahip), uygulamaya geniş katılım sağlayan davranış için idealdir — bu davranışı her uç noktada tekrarlamak yorucu ve hatalara açık olurdu.

**Middleware** (global, ham istek/yanıt seviyesi) ve **bağımlılıklar** (uç noktaya özel, ayrıştırılmış/yazılı değerlere ve DI'ye erişime sahip — kimlik doğrulama ve doğrulama için daha iyi) arasındaki farkı bilmek, doğru aracı seçmek için anahtardır.

CORS ve sıkıştırma gibi yaygın ihtiyaçlar yerleşik middleware tarafından işlenir, özel middleware ise logging ve enstrümantasyonu kapsar — bu, iyi yapılandırılmış, gözlemlenebilir API'ler inşa etmek için pratik, sık kullanılan bilgidir.