Как работает middleware в FastAPI?

Question

Accepted Answer

**Middleware** в FastAPI — это код, который выполняется для **каждого запроса и ответа** — обёртывая ваши endpoint'ы для обработки сквозных задач, таких как логирование, измерение времени, CORS и добавление заголовков. FastAPI использует систему middleware Starlette (она основана на ASGI).

## Написание пользовательского 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
```

Паттерн: код до `await call_next(request)` выполняется **на входе** (перед endpoint'ом), `call_next` вызывает endpoint, а код после выполняется **на выходе** (модифицируя ответ). Это оборачивает каждый запрос — здесь добавляя заголовок времени ко всем ответам.

## Поток запроса/ответа

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

```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 обычно добавляется через `add_middleware` — CORS (разрешить кросс-доменные запросы), GZip (сжимать ответы) и проверка доверенных хостов — типичные встроенные middleware.

## Распространённые использования 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 против зависимостей

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

## Почему это важно

Middleware — это правильный механизм для **глобальных, сквозных задач** в FastAPI — логики, которая должна применяться к каждому запросу и ответу, таких как логирование, измерение времени запроса, CORS, сжатие и пользовательские заголовки.

Понимание этого важно для правильной структуризации приложений: middleware оборачивает все endpoint'ы (выполняется перед и после, с возможностью модифицировать как запрос, так и ответ), делая его идеальным для поведения на уровне приложения, которое было бы утомительно и подвержено ошибкам повторять в каждом endpoint'е.

Знание различий между **middleware** (глобальный, низкоуровневый запрос/ответ) и **зависимостями** (per-endpoint, с доступом к разобранным/типизированным значениям и DI — лучше для аутентификации и валидации) является ключевым для выбора правильного инструмента.

Общие потребности, такие как CORS и сжатие, обрабатываются встроенным middleware, в то время как пользовательское middleware охватывает логирование и инструментирование — делая эту практическую, часто используемую информацию важной для создания хорошо структурированных и наблюдаемых API.