Rate limiting, загрузка файлов и deprecation в FastAPI

Python Backend

Как защитить FastAPI-сервис от перегрузки через rate limiting с заголовками RateLimit-*, принимать и отдавать файлы через multipart и StreamingResponse, и плавно снимать устаревшие эндпоинты через Sunset и 410 Gone.

Опубликовано 19 июня 2026 обновлено 28 июня 2026 ~7 мин чтения Автор: Вадим Викулин

← назад к разделу

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

Rate limiting: как остановить лавину запросов

Представьте, что один клиент в секунду делает тысячи запросов — намеренно или из-за бага. Без ограничений сервис ляжет. Rate limiting — это барьер: разрешаем, скажем, 100 запросов в минуту на клиента, остальные отклоняем с кодом 429 Too Many Requests.

Важный момент: rate limiting не реализуют внутри обработчика запроса. Его выносят в middleware или внешний балансировщик (nginx, API Gateway). Обработчик просто не должен знать о лимитах.

Middleware с заголовками RateLimit-*

from fastapi import FastAPI, Request, Response
from fastapi.responses import JSONResponse
import time

app = FastAPI(redirect_slashes=False)

RATE_LIMIT = 100
WINDOW_SECONDS = 60

# Упрощённый счётчик (in-process, для production — Redis)
_counters: dict[str, tuple[int, float]] = {}


@app.middleware("http")
async def rate_limit_middleware(request: Request, call_next):
    client_id = request.headers.get("X-Client-Id", request.client.host)
    now = time.time()

    count, window_start = _counters.get(client_id, (0, now))
    if now - window_start > WINDOW_SECONDS:
        count, window_start = 0, now

    remaining = RATE_LIMIT - count
    reset_at = int(window_start + WINDOW_SECONDS)

    if remaining <= 0:
        return JSONResponse(
            status_code=429,
            media_type="application/problem+json",
            content={
                "type": "urn:problem:order-service:rate-limit-exceeded",
                "status": 429,
                "title": "Too Many Requests",
                "detail": f"Превышен лимит запросов. Повторите через {reset_at - int(now)} секунд.",
                "code": "RATE_LIMIT_EXCEEDED",
            },
            headers={
                "Retry-After": str(reset_at - int(now)),
                "RateLimit-Limit": str(RATE_LIMIT),
                "RateLimit-Remaining": "0",
                "RateLimit-Reset": str(reset_at),
            },
        )

    _counters[client_id] = (count + 1, window_start)
    response: Response = await call_next(request)
    response.headers["RateLimit-Limit"] = str(RATE_LIMIT)
    response.headers["RateLimit-Remaining"] = str(remaining - 1)
    response.headers["RateLimit-Reset"] = str(reset_at)
    return response

Несколько деталей, которые стоит понять:

Retry-After — сколько секунд подождать перед повтором. Без него клиент не знает, когда стучаться снова, и будет долбиться сразу.
RateLimit-Limit/Remaining/Reset — добавляются не только в ответ 429, но и в каждый успешный ответ. Клиент видит остаток запасов заранее и может самостоятельно замедлиться.
RateLimit-Reset — Unix timestamp момента сброса окна.

Как выглядит ответ 429

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 23
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1750291200

{
  "type": "urn:problem:order-service:rate-limit-exceeded",
  "status": 429,
  "title": "Too Many Requests",
  "detail": "Превышен лимит запросов. Повторите через 23 секунды.",
  "code": "RATE_LIMIT_EXCEEDED"
}

И в успешных ответах тоже

HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Limit: 100
RateLimit-Remaining: 57
RateLimit-Reset: 1750291200

{ "orderId": "ord-9182", "status": "CONFIRMED" }

Благодаря заголовкам в успешных ответах клиент знает остаток прямо сейчас — и может притормозить сам, не дожидаясь 429.

Описать 429 в OpenAPI

FastAPI code-first: 429 указывают явно через responses в декораторе, чтобы потребители API видели это в документации.

from fastapi import APIRouter
from pydantic import BaseModel

router = APIRouter(prefix="/api/v1", tags=["Orders"])


class OrderResponse(BaseModel):
    model_config = {"populate_by_name": True}
    orderId: str
    status: str


@router.get(
    "/orders/{order_id}",
    response_model=OrderResponse,
    operation_id="getOrder",
    summary="Получить заказ",
    responses={
        429: {
            "description": "Too Many Requests",
            "headers": {
                "Retry-After": {"schema": {"type": "integer"}},
                "RateLimit-Limit": {"schema": {"type": "integer"}},
                "RateLimit-Remaining": {"schema": {"type": "integer"}},
                "RateLimit-Reset": {"schema": {"type": "integer"}},
            },
            "content": {
                "application/problem+json": {
                    "schema": {"$ref": "#/components/schemas/ProblemDetails"}
                }
            },
        }
    },
)
async def get_order(order_id: str) -> OrderResponse:
    ...

Загрузка файлов: почему не Base64 в JSON

Файл — бинарные данные. Если передать его Base64-строкой в JSON-теле, размер вырастает на 33% и теряется возможность передавать данные потоком. Правильный транспорт — multipart/form-data и тип UploadFile в FastAPI.

Приём файла через UploadFile

from fastapi import APIRouter, UploadFile, File, Form
from fastapi.responses import StreamingResponse, Response
from pydantic import BaseModel
from datetime import datetime, timezone

router = APIRouter(prefix="/api/v1", tags=["Orders"])


class AttachmentResponse(BaseModel):
    attachmentId: str
    fileName: str
    contentType: str
    size: int
    uploadedAt: str


@router.post(
    "/orders/{order_id}/attachments",
    response_model=AttachmentResponse,
    status_code=201,
    operation_id="uploadOrderAttachment",
    summary="Загрузить вложение к заказу",
    response_model_exclude_none=True,
)
async def upload_order_attachment(
    order_id: str,
    file: UploadFile = File(..., description="Максимум 10 МБ. PDF, PNG, JPG"),
    description: str | None = Form(None, max_length=500),
    response: Response = None,
) -> AttachmentResponse:
    content = await file.read()
    if len(content) > 10 * 1024 * 1024:
        raise FileTooLargeError()

    allowed = {"application/pdf", "image/png", "image/jpeg"}
    if file.content_type not in allowed:
        raise UnsupportedMediaTypeError()

    attachment_id = "att-" + order_id[:8]
    response.headers["Location"] = (
        f"/api/v1/orders/{order_id}/attachments/{attachment_id}"
    )

    return AttachmentResponse(
        attachmentId=attachment_id,
        fileName=file.filename,
        contentType=file.content_type,
        size=len(content),
        uploadedAt=datetime.now(timezone.utc).isoformat(),
    )

UploadFile даёт доступ к filename, content_type и к содержимому через await file.read(). Ограничения на размер и допустимые типы проверяют явно в обработчике.

Как выглядит HTTP-запрос

POST /api/v1/orders/ord-9182/attachments
Content-Type: multipart/form-data; boundary=----Boundary7MA4

------Boundary7MA4
Content-Disposition: form-data; name="file"; filename="invoice.pdf"
Content-Type: application/pdf

<binary data>
------Boundary7MA4
Content-Disposition: form-data; name="description"

Счёт за февраль
------Boundary7MA4--

Ответ 201 с метаданными

{
  "attachmentId": "att-ord-9182",
  "fileName": "invoice.pdf",
  "contentType": "application/pdf",
  "size": 204800,
  "uploadedAt": "2026-06-19T09:15:00+00:00"
}

Ответ 201 Created + заголовок Location + полное тело ресурса.

Скачивание через StreamingResponse

import aiofiles

@router.get(
    "/orders/{order_id}/attachments/{attachment_id}",
    operation_id="downloadOrderAttachment",
    summary="Скачать вложение заказа",
)
async def download_order_attachment(
    order_id: str,
    attachment_id: str,
) -> StreamingResponse:
    file_path = resolve_attachment_path(order_id, attachment_id)
    file_name = "invoice.pdf"
    content_type = "application/pdf"

    async def file_stream():
        async with aiofiles.open(file_path, "rb") as f:
            while chunk := await f.read(65536):
                yield chunk

    return StreamingResponse(
        file_stream(),
        media_type=content_type,
        headers={
            "Content-Disposition": f'attachment; filename="{file_name}"',
        },
    )

Заголовок Content-Disposition: attachment; filename="invoice.pdf" — без него браузер и HTTP-клиент не знают, под каким именем сохранять файл.

Для небольших статических файлов подходит FileResponse — он сам выставляет Content-Disposition и Content-Length:

from fastapi.responses import FileResponse

return FileResponse(
    path=file_path,
    media_type="application/pdf",
    filename="invoice.pdf",
)

Deprecation: как плавно убрать старый эндпоинт

Рано или поздно API меняется: появляется /v2, старый маршрут становится устаревшим. Резко удалить его нельзя — у клиентов нет времени перейти. Правильный путь — объявить deprecation, дать срок и только потом убрать.

В FastAPI это делается в два шага.

Шаг 1. Пометить в OpenAPI

@router.get(
    "/orders/{order_id}/status",
    operation_id="getOrderStatusLegacy",
    summary="Получить статус заказа",
    deprecated=True,
    description=(
        "DEPRECATED: используйте GET /api/v2/orders/{order_id}. "
        "Будет удалён после 2026-12-01."
    ),
)
async def get_order_status_legacy(order_id: str):
    ...

deprecated=True помечает операцию в /openapi.json — Swagger UI перечёркивает её и выделяет предупреждением. Это видят разработчики при просмотре документации.

Шаг 2. Добавить HTTP-заголовки

Пометка в OpenAPI видна только при просмотре документации. Но клиенты, которые уже используют эндпоинт, документацию не читают. Для них — HTTP-заголовки в каждом ответе. Их удобно добавлять через Depends:

from fastapi import Depends, Response


def deprecation_headers(
    response: Response,
    sunset_date: str = "Thu, 01 Dec 2026 00:00:00 GMT",
    successor: str = "/api/v2/orders/{order_id}",
):
    response.headers["Sunset"] = sunset_date
    response.headers["Deprecation"] = "true"
    response.headers["Link"] = f'<{successor}>; rel="successor-version"'


@router.get(
    "/orders/{order_id}/status",
    operation_id="getOrderStatusLegacy",
    summary="Получить статус заказа",
    deprecated=True,
    description=(
        "DEPRECATED: используйте GET /api/v2/orders/{order_id}. "
        "Будет удалён после 2026-12-01."
    ),
    dependencies=[Depends(deprecation_headers)],
)
async def get_order_status_legacy(order_id: str):
    return {"status": "PROCESSING"}

Каждый ответ будет содержать:

HTTP/1.1 200 OK
Sunset: Thu, 01 Dec 2026 00:00:00 GMT
Deprecation: true
Link: </api/v2/orders/{order_id}>; rel="successor-version"

{ "status": "PROCESSING" }

Sunset (RFC 8594) — точная дата отключения в HTTP-date формате. Без даты клиент не может планировать миграцию.
Deprecation: true — машиночитаемый флаг для SDK и мониторинга.
Link с rel="successor-version" — клиент знает, куда переходить.

Шаг 3. После даты Sunset — 410 Gone

После наступления даты Sunset handler заменяется на 410 Gone. Код 404 здесь не подходит: 404 означает «не знаю такого», а 410 означает «знаю, но убрал намеренно».

from fastapi import HTTPException
from fastapi.responses import JSONResponse
from datetime import datetime, timezone


SUNSET = datetime(2026, 12, 1, tzinfo=timezone.utc)


@router.get(
    "/orders/{order_id}/status",
    operation_id="getOrderStatusRemoved",
    include_in_schema=False,
)
async def get_order_status_gone(order_id: str):
    if datetime.now(timezone.utc) >= SUNSET:
        return JSONResponse(
            status_code=410,
            media_type="application/problem+json",
            content={
                "type": "urn:problem:order-service:endpoint-removed",
                "status": 410,
                "title": "Gone",
                "detail": (
                    "Эндпоинт удалён. "
                    "Используйте GET /api/v2/orders/{order_id}."
                ),
                "code": "ENDPOINT_REMOVED",
            },
        )
    return {"status": "PROCESSING"}

include_in_schema=False — удалённый эндпоинт не фигурирует в /openapi.json, но физически ещё принимает запросы и отвечает 410. Клиент получает понятную ошибку с указанием альтернативы.

Рекомендуемый период между объявлением deprecation и датой Sunset — от 6 до 12 месяцев. Этого хватает крупным потребителям, чтобы переключиться.

Коротко

Rate limiting реализуют в middleware, не в обработчике. Ответ 429 обязательно содержит Retry-After и RateLimit-Limit/Remaining/Reset.
RateLimit-* добавляют не только в 429, но и в каждый успешный ответ — клиент видит остаток запасов заранее.
Файлы принимают через UploadFile + multipart/form-data, не через Base64 в JSON.
При скачивании всегда указывают Content-Disposition: attachment; filename="..." — иначе клиент не знает имя файла.
Deprecation = два шага: deprecated=True в декораторе (видно в Swagger) + заголовки Sunset/Deprecation/Link в ответах (видно клиентам).
Sunset без конкретной даты — бессмысленен: дату ставят сразу, минимум за 6 месяцев.
После даты Sunset эндпоинт возвращает 410 Gone с указанием альтернативы.

Что почитать дальше

Ошибки RFC 9457 — как форматировать 429 и 410 как problem+json.
Заголовки и трассировка — кастомные заголовки, Idempotency-Key, traceparent.
Версионирование — как переходить с v1 на v2 и когда deprecation неизбежен.