FastAPI middleware: общая логика для запросов

Категория: Backend · Язык: Python · Обновлено:

Middleware оборачивает каждый HTTP-запрос: добавляет request ID, измеряет время, пишет лог или проверяет заголовки. В FastAPI его объявляют через @app.middleware("http") или класс BaseHTTPMiddleware. Код получает Request, вызывает call_next и возвращает Response, поэтому middleware выполняется до и после обработчика.

Добавить request ID и время ответа

Python
import time
import uuid
from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def add_request_id(request: Request, call_next):
    request_id = request.headers.get("X-Request-ID") or str(uuid.uuid4())
    request.state.request_id = request_id
    started = time.perf_counter()

    response = await call_next(request)

    response.headers["X-Request-ID"] = request_id
    response.headers["X-Process-Time"] = f"{time.perf_counter() - started:.4f}"
    return response

@app.get("/")
async def root(request: Request):
    return {"request_id": request.state.request_id}

call_next передаёт запрос следующему слою и возвращает ответ. До вызова можно подготовить request.state, после — добавить заголовки. X-Request-ID из клиента полезен для трассировки, но не доверяйте ему как идентификатору безопасности: генерируйте свой, если заголовка нет, и ограничивайте длину.

Учесть порядок middleware

Python
@app.middleware("http")
async def add_security_headers(request: Request, call_next):
    response = await call_next(request)
    response.headers["X-Content-Type-Options"] = "nosniff"
    return response

Middleware выполняются в обратном порядке добавления: последний добавленный слой оказывается внешним. CORS, сжатие и логирование стоит располагать осознанно; ошибка в порядке приводит к тому, что заголовки не попадают в ответ или исключение не логируется. Для CORS используйте CORSMiddleware, а не самодельный слой.

Не читайте тело запроса в middleware без необходимости: await request.body() расходует поток, и обработчик может получить пустое тело. Не подавляйте исключения — логируйте и пробрасывайте дальше. Для тяжёлой логики на чистом ASGI пишите class-based middleware, чтобы избежать накладных расходов BaseHTTPMiddleware.

BaseHTTPMiddleware может влиять на streaming и background tasks; проверяйте SSE и большие файлы. В тестах TestClient выполняет middleware как в реальном приложении, поэтому заголовки можно проверить без запуска uvicorn.

Документация: FastAPI middleware, Starlette middleware.