Skip to content

FastAPI Шпаргалка

Современный быстрый веб-фреймворк Python для создания API.

01

Начало работы

Первое API

FastAPI построен на Starlette и Pydantic. uvicorn — ASGI-сервер. --reload включает автоперезагрузку при разработке.

fastapi
# install FastAPI and uvicorn
pip install fastapi uvicorn

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

# run: uvicorn main:app --reload

Запуск через Uvicorn

Запись 'main:app' означает модуль 'main' и переменную 'app'. Используйте --reload только при разработке; в production запускайте без него и под менеджером процессов.

fastapi
# development with auto-reload
uvicorn main:app --reload

# specify host and port
uvicorn main:app --host 0.0.0.0 --port 8000

# run programmatically
import uvicorn
if __name__ == "__main__":
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

Асинхронные обработчики путей

Обработчики путей можно объявлять через 'def' (выполняется в пуле потоков) или 'async def'. Используйте async def, когда функция работает с вводом-выводом через асинхронные библиотеки; блокирующие вызовы внутри async def останавливают цикл событий.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "hello"}

@app.get("/sync")
def read_sync():
    return {"message": "sync also works"}

# use async when calling async libs (httpx, databases)
@app.get("/data")
async def fetch_data():
    import httpx
    async with httpx.AsyncClient() as client:
        r = await client.get("https://api.example.com")
    return r.json()

Декораторы обработчиков путей

FastAPI поддерживает все HTTP-методы: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD. Каждому соответствует декоратор. status_code= в декораторе переопределяет стандартный код успеха.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
def list_items(): ...

@app.post("/items")
def create_item(): ...

@app.put("/items/{item_id}")
def replace_item(item_id: int): ...

@app.patch("/items/{item_id}")
def update_item(item_id: int): ...

@app.delete("/items/{item_id}")
def delete_item(item_id: int): ...

@app.options("/items")
def options_items(): ...

@app.head("/items")
def head_items(): ...

JSON-ответ и статус

Возврат dict или list автоматически преобразуется в JSON с кодом 200 (или вашим status_code). Для полного контроля над статусом, заголовками и содержимым возвращайте JSONResponse или Response напрямую.

fastapi
from fastapi import FastAPI, status
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/plain")
def plain():
    return {"key": "value"}  # auto JSON, 200 OK

@app.post("/created", status_code=status.HTTP_201_CREATED)
def created():
    return {"id": 1}

@app.get("/custom")
def custom():
    return JSONResponse(
        status_code=418,
        content={"error": "I'm a teapot"},
        headers={"X-Custom": "yes"},
    )

Структура проекта

Растущее приложение разбивайте на модули с APIRouter и регистрируйте через app.include_router(). Схемы Pydantic, настройку БД и зависимости держите в отдельных файлах для удобства поддержки.

fastapi
myapp/
  main.py              # creates the FastAPI app
  routers/
    users.py           # APIRouter for /users
    items.py           # APIRouter for /items
  models/
    schemas.py         # Pydantic models
    database.py        # DB engine & session
  dependencies.py      # shared Depends functions
  tests/
    test_main.py

# main.py
from fastapi import FastAPI
from routers import users, items
app = FastAPI()
app.include_router(users.router)
app.include_router(items.router, prefix="/items")
02

Параметры пути

Базовые параметры пути

Значения из пути приходят строками, если не добавить аннотацию типа. Имя параметра в пути должно точно совпадать с именем аргумента функции.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id):
    return {"item_id": item_id}

# GET /items/42 -> {"item_id": "42"}  (string by default)

Преобразование типов

Аннотация типа (int, float, bool, str, Enum) заставляет FastAPI проверить и преобразовать значение пути. Некорректные значения дают ответ 422 с понятным сообщением об ошибке.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

# GET /items/3   -> {"item_id": 3}
# GET /items/abc -> 422 Validation Error (not an integer)

Валидация пути

Path() добавляет метаданные и ограничения к параметру пути. Числовые ограничения: ge (>=), gt (>), le (<=), lt (<). Параметры пути всегда обязательны, поэтому Path() не может задать значение по умолчанию.

fastapi
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(
    item_id: int = Path(
        title="The ID of the item",
        description="Must be a positive integer",
        ge=1,
        le=1000,
    ),
):
    return {"item_id": item_id}

Числовые ограничения

Используйте ge/gt/le/lt для параметров пути int или float, чтобы задать числовые диапазоны. Вместе они дают точную проверку границ с автоматическими ошибками 422.

fastapi
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/ratio/{value}")
def ratio(
    value: float = Path(gt=0, lt=1),  # 0 < value < 1
):
    return {"value": value}

@app.get("/page/{page}")
def page(
    page: int = Path(ge=1),       # >= 1
    size: int = Path(le=100),     # <= 100
):
    return {"page": page, "size": size}

Порядок маршрутов важен

Маршруты сопоставляются в порядке объявления. Объявляйте конкретные пути вроде /users/me раньше динамических шаблонов вроде /users/{user_id}, иначе динамический маршрут перекроет конкретный.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/users/me")
def read_current_user():
    return {"user": "me"}

@app.get("/users/{user_id}")
def read_user(user_id: str):
    return {"user_id": user_id}

# /users/me MUST be declared before /users/{user_id}
# otherwise 'me' would match the {user_id} pattern

Enum в параметрах пути

Тип Enum для параметра пути ограничивает его заданными значениями и создаёт enum-схему в документации OpenAPI. Наследуйтесь от (str, Enum), чтобы значения сериализовались как строки.

fastapi
from enum import Enum
from fastapi import FastAPI

class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"

app = FastAPI()

@app.get("/models/{model_name}")
def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model": model_name, "layers": 5}
    return {"model": model_name}

# GET /models/resnet -> {"model": "resnet"}
03

Query-параметры

Базовые query-параметры

Параметры функции, которых нет в пути, становятся query-параметрами. Значение по умолчанию делает их необязательными; оно используется, когда ключа в запросе нет.

fastapi
from fastapi import FastAPI

app = FastAPI()

fake_items = [{"item": "a"}, {"item": "b"}, {"item": "c"}]

@app.get("/items")
def list_items(skip: int = 0, limit: int = 10):
    return fake_items[skip : skip + limit]

# GET /items?skip=0&limit=2
# GET /items                -> skip=0, limit=10

Необязательные query-параметры

Используйте Optional[str] = None (или str | None = None в Python 3.10+) для query-параметра, который можно не передавать. Обязательные параметры просто не имеют значения по умолчанию.

fastapi
from typing import Optional
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: str, q: Optional[str] = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

# GET /items/1?q=hello
# GET /items/1            (q is None)

Валидация query-параметров

Query() добавляет проверки: min_length/max_length для строк, ge/gt/le/lt для чисел, pattern (regex) для формата строки. Используйте default=, чтобы задать значение и при этом применить ограничения.

fastapi
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/search")
def search(q: str = Query(min_length=3, max_length=50, pattern="^[a-zA-Z]+$")):
    return {"q": q}

@app.get("/page")
def page(limit: int = Query(default=10, ge=1, le=100)):
    return {"limit": limit}

Преобразование в bool

Bool-параметры принимают много истинных значений: true, 1, yes, on (без учёта регистра). Всё остальное трактуется как false. Некорректные значения вроде ?active=maybe дают 422.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/flags")
def flags(active: bool = False):
    return {"active": active}

# GET /flags?active=true   -> {"active": true}
# GET /flags?active=1      -> {"active": true}
# GET /flags?active=yes    -> {"active": true}
# GET /flags?active=off    -> {"active": false}

Списки в query-параметрах

Параметр List[str] принимает один и тот же ключ, повторённый в строке запроса. Используйте Query(default=[]) для пустого списка по умолчанию или Query(default=None), чтобы разрешить отсутствие значения.

fastapi
from typing import List
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
def list_items(q: List[str] = Query(default=[])):
    return {"q": q}

# GET /items?q=a&q=b&q=c  -> {"q": ["a", "b", "c"]}
# declare default=None to accept a list or null

Обязательные query-параметры

Query(...) (многоточие) объявляет обязательный query-параметр, сохраняя метаданные валидации. Параметр с аннотацией без значения по умолчанию и без Query(...) тоже обязателен.

fastapi
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
def read_item(q: str = Query(...)):
    return {"q": q}

# GET /items?q=hello   -> ok
# GET /items           -> 422 (q is required)
# Query(...) (Ellipsis) marks a parameter as required
04

Тело запроса (Pydantic)

Основы BaseModel

BaseModel Pydantic, объявленный параметром функции, становится JSON-телом запроса. FastAPI проверяет данные, преобразует типы и возвращает 422 при ошибке. Поля со значениями по умолчанию необязательны.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    in_stock: bool = True

app = FastAPI()

@app.post("/items")
def create_item(item: Item):
    return item

# POST /items  body: {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5, "in_stock": true}

Типы полей и ограничения

Field() добавляет ограничения и метаданные атрибутам модели: min_length/max_length для строк, gt/ge/lt/le для чисел, default_factory для изменяемых значений по умолчанию. model_config с json_schema_extra добавляет примеры в документацию.

fastapi
from pydantic import BaseModel, Field
from typing import Optional

class Item(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0, description="must be positive")
    tax: Optional[float] = None
    tags: list[str] = Field(default_factory=list)

    model_config = {
        "json_schema_extra": {
            "examples": [{"name": "Apple", "price": 0.5, "tags": ["fruit"]}]
        }
    }

Вложенные модели

Модели можно вкладывать: объявите другую BaseModel как тип поля. FastAPI рекурсивно проверяет всю вложенную структуру, а сгенерированная схема OpenAPI отражает вложенные объекты.

fastapi
from pydantic import BaseModel
from typing import Optional

class Image(BaseModel):
    url: str
    name: str

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    image: Optional[Image] = None
    images: list[Image] = []

# valid body:
# {"name": "Phone", "image": {"url": "http://x/a.png", "name": "a"}}

Валидация полей

Используйте @field_validator (Pydantic v2), чтобы добавить свою логику проверки поля. Бросьте ValueError, чтобы отклонить ввод (FastAPI вернёт 422). Верните (возможно, преобразованное) значение, чтобы сохранить его.

fastapi
from pydantic import BaseModel, field_validator

class User(BaseModel):
    name: str
    email: str

    @field_validator("email")
    @classmethod
    def email_must_contain_at(cls, v: str) -> str:
        if "@" not in v:
            raise ValueError("must contain @")
        return v.lower()

    @field_validator("name")
    @classmethod
    def name_stripped(cls, v: str) -> str:
        return v.strip()

Необязательные поля и значения по умолчанию

Поле обязательно только если у него нет значения по умолчанию и оно не Optional. Optional[str] = None — стандартный шаблон необязательного nullable-поля; обычное значение вроде 0.0 делает поле необязательным с этим значением.

fastapi
from pydantic import BaseModel
from typing import Optional

class Item(BaseModel):
    name: str                       # required
    description: Optional[str] = None  # optional, defaults to None
    price: float = 0.0              # optional, defaults to 0.0
    tags: list[str] = []            # optional, defaults to empty list

# All of these are valid:
# {"name": "X"}
# {"name": "X", "price": 9.99, "tags": ["a"]}

Тело вместе с путём и query

Параметры пути, query и тела могут сосуществовать в одной операции. FastAPI решает так: если параметр есть в пути — это параметр пути; Pydantic-модель (или Body()) — тело; иначе query. Необязательному телу нужно значение по умолчанию None.

fastapi
from fastapi import FastAPI, Path, Query
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.put("/items/{item_id}")
def update_item(
    item_id: int = Path(ge=1),
    q: Optional[str] = Query(default=None),
    item: Item = None,
):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result["q"] = q
    return result
05

Модель ответа

Основы response_model

response_model фильтрует возвращаемые данные до полей, описанных в модели, даже если вы вернули объект с лишними полями. Это стандартный способ скрыть чувствительные поля вроде паролей.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class User(BaseModel):
    username: str
    email: str
    hashed_password: str

class UserOut(BaseModel):
    username: str
    email: str

app = FastAPI()

@app.get("/users/me", response_model=UserOut)
def read_user():
    return User(username="bob", email="[email protected]", hashed_password="secret")

# response: {"username": "bob", "email": "[email protected]"}  (no password)

Исключение полей

response_model_include и response_model_exclude позволяют задать белый или чёрный список полей для маршрута без создания новых моделей. Передавайте множество имён полей. Они применяются дополнительно к response_model.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    secret: str

app = FastAPI()

@app.get("/items/{id}", response_model=Item, response_model_exclude={"secret"})
def read_item(id: int):
    return {"name": "Apple", "price": 0.5, "secret": "hidden"}

@app.get("/items", response_model=list[Item], response_model_include={"name", "price"})
def list_items():
    return [{"name": "Apple", "price": 0.5, "secret": "x"}]

Ответ-список

Используйте response_model=list[Model] (или List[Model]), чтобы объявить, что endpoint возвращает массив объектов. FastAPI проверяет и сериализует каждый элемент списка.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.get("/items", response_model=list[Item])
def list_items():
    return [
        {"name": "Apple", "price": 0.5},
        {"name": "Banana", "price": 0.3},
    ]

# response: [{"name": "Apple", "price": 0.5}, {"name": "Banana", "price": 0.3}]

Исключение не заданных и значений по умолчанию

exclude_unset опускает поля, которые клиент не присылал (остаются только явно заданные). exclude_defaults опускает поля, равные значениям по умолчанию; exclude_none опускает поля со значением None. Полезно для разреженных ответов.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float = 0.0
    tax: float = 0.0

app = FastAPI()

@app.get("/items/{id}", response_model=Item, response_model_exclude_unset=True)
def read_item(id: int):
    return {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5}   (description, tax omitted)

# also: response_model_exclude_defaults=True
#       response_model_exclude_none=True

Ответ через alias

Field(alias=...) позволяет входному JSON использовать другое имя ключа, чем атрибут Python. response_model_by_alias=True выводит данные тоже по alias. populate_by_name=True дополнительно разрешает исходное имя атрибута на входе.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel, ConfigDict, Field

class Item(BaseModel):
    model_config = ConfigDict(populate_by_name=True)
    name: str = Field(alias="itemName")
    price: float

app = FastAPI()

@app.post("/items", response_model=Item, response_model_by_alias=True)
def create(item: Item):
    return item

# input:  {"itemName": "Apple", "price": 0.5}
# output: {"itemName": "Apple", "price": 0.5}

Ответ в виде словаря

Возврат dict или list автоматически сериализуется в JSON. response_class меняет тип ответа по умолчанию (HTMLResponse, PlainTextResponse), а возврат подкласса Response даёт полный контроль.

fastapi
from fastapi import FastAPI
from fastapi.responses import JSONResponse, PlainTextResponse

app = FastAPI()

@app.get("/dict")
def dict_resp():
    return {"a": 1, "b": 2}      # auto JSON

@app.get("/text", response_class=PlainTextResponse)
def text_resp():
    return "plain text response"

@app.get("/raw")
def raw_resp():
    return JSONResponse(content={"a": 1}, status_code=200)
06

Формы и UploadFile

Данные формы

Form() объявляет параметр, разбираемый из application/x-www-form-urlencoded или multipart-формы. В одной операции нельзя смешивать Form() с JSON-телом (BaseModel) — выберите один тип содержимого.

fastapi
from fastapi import FastAPI, Form

app = FastAPI()

@app.post("/login")
def login(username: str = Form(), password: str = Form()):
    return {"username": username}

# Content-Type: application/x-www-form-urlencoded
# body: username=bob&password=secret

Основы UploadFile

UploadFile — потоковое представление файла с .filename, .content_type, .read(), .write(), .close(). В async def используйте 'await file.read()'. Для больших файлов предпочитайте file.file (SpooledTemporaryFile), чтобы не грузить всё в память.

fastapi
from fastapi import FastAPI, UploadFile, File

app = FastAPI()

@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
    contents = await file.read()
    return {
        "filename": file.filename,
        "size": len(contents),
        "content_type": file.content_type,
    }

Несколько файлов

Объявите list[UploadFile], чтобы принять несколько файлов в одном запросе. Каждый файл отправляется с одним и тем же именем поля. Порядок файлов в списке совпадает с порядком отправки.

fastapi
from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/uploads")
async def upload_many(files: list[UploadFile]):
    return [
        {"filename": f.filename, "size": len(await f.read())}
        for f in files
    ]

# curl: curl -F "[email protected]" -F "[email protected]" http://localhost:8000/uploads

Файл и форма вместе

Form() и UploadFile (File()) можно сочетать в одном endpoint, так как оба используют multipart/form-data. Но их по-прежнему нельзя сочетать с JSON-телом BaseModel.

fastapi
from fastapi import FastAPI, UploadFile, File, Form

app = FastAPI()

@app.post("/items")
async def create_item(
    name: str = Form(),
    description: str = Form(),
    file: UploadFile = File(),
):
    return {
        "name": name,
        "description": description,
        "file": file.filename,
    }

Сохранение загруженного файла

Для небольших файлов shutil.copyfileobj эффективно переписывает SpooledTemporaryFile на диск. Для очень больших файлов читайте частями (например, по 1 МБ), чтобы экономить память. Всегда очищайте file.filename, чтобы избежать path traversal.

fastapi
import shutil
from pathlib import Path
from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/save")
async def save_file(file: UploadFile):
    dest = Path("uploads") / file.filename
    dest.parent.mkdir(exist_ok=True)
    with dest.open("wb") as buf:
        shutil.copyfileobj(file.file, buf)
    return {"saved_to": str(dest)}

# async alternative for large files:
# async with dest.open("wb") as buf:
#     while chunk := await file.read(1024 * 1024):
#         buf.write(chunk)

Метаданные и размер файла

Проверяйте file.content_type и размер до обработки. После read() курсор в конце; вызовите 'await file.seek(0)', чтобы вернуться к началу, если нужно читать снова. Настоящая проверка типа должна смотреть на magic bytes, а не только на заголовок.

fastapi
from fastapi import FastAPI, UploadFile, File

app = FastAPI()

@app.post("/validate")
async def validate(file: UploadFile = File(...)):
    # allowed types
    allowed = {"image/png", "image/jpeg"}
    if file.content_type not in allowed:
        return {"error": "unsupported type"}

    contents = await file.read()
    max_size = 5 * 1024 * 1024  # 5 MB
    if len(contents) > max_size:
        return {"error": "file too large"}

    await file.seek(0)  # rewind so later reads work
    return {"filename": file.filename, "size": len(contents)}
07

Заголовки и cookie

Параметры заголовков

Header() объявляет параметр, читаемый из заголовков запроса. FastAPI превращает подчёркивания в именах Python в дефисы (x_token -> X-Token). convert_underscores=False отключает это поведение.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/items")
def read_items(user_agent: str | None = Header(default=None)):
    return {"User-Agent": user_agent}

# Header names are case-insensitive; an underscore in the
# parameter (x_token) is converted to a hyphen (X-Token) automatically.
@app.get("/secure")
def secure(x_token: str = Header()):
    return {"x-token": x_token}

Параметры cookie

Cookie() читает значение из заголовка Cookie запроса. Как и query-параметры, cookie без значения по умолчанию обязательны, и к ним можно применять проверки (min_length, max_length и др.).

fastapi
from fastapi import FastAPI, Cookie

app = FastAPI()

@app.get("/session")
def read_session(session_id: str | None = Cookie(default=None)):
    if session_id:
        return {"session_id": session_id}
    return {"message": "no session"}

# Reads the 'session_id' cookie from the Cookie header.

Установка cookie в ответе

Внедрите Response и вызовите set_cookie(), чтобы записать cookie в исходящий ответ. Используйте httponly=True (блокирует доступ из JS), secure=True (только HTTPS) и samesite='lax'/'strict' для защиты от CSRF. Тело ответа возвращается как обычно.

fastapi
from fastapi import FastAPI, Response

app = FastAPI()

@app.post("/login")
def login(response: Response):
    response.set_cookie(
        key="session_id",
        value="abc123",
        httponly=True,
        max_age=1800,
        secure=True,
        samesite="lax",
    )
    return {"message": "logged in"}

@app.post("/logout")
def logout(response: Response):
    response.delete_cookie("session_id")
    return {"message": "logged out"}

Свои заголовки ответа

Устанавливайте заголовки на внедрённом Response, чтобы добавить их к JSON-ответу, который строит FastAPI, или передавайте headers= при возврате подкласса Response напрямую. Свои заголовки часто используют для информации о rate limit и времени обработки.

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

app = FastAPI()

@app.get("/data")
def get_data(response: Response):
    response.headers["X-Process-Time"] = "0.05"
    response.headers["X-Custom-Header"] = "hello"
    return {"data": 1}

@app.get("/direct")
def direct():
    return JSONResponse(
        content={"data": 1},
        headers={"X-Source": "direct"},
    )

Стандартные заголовки

Обычные заголовки вроде Host, Accept, Authorization, If-None-Match доступны через Header(). Для Authorization предпочитайте встроенные средства безопасности (HTTPBearer, OAuth2): они сами разбирают заголовок и документируют его в OpenAPI.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/info")
def info(
    host: str | None = Header(default=None),
    accept: str | None = Header(default=None),
    authorization: str | None = Header(default=None),
    if_none_match: str | None = Header(default=None),
):
    return {"host": host, "accept": accept}

Повторяющиеся заголовки

Объявление типа-списка для параметра Header собирает все повторяющиеся значения заголовка в список. Это полезно для заголовков вроде Set-Cookie (в ответе) или любого своего заголовка, который может встречаться несколько раз.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/multi")
def multi(x_token: list[str] | None = Header(default=None)):
    return {"x_token": x_token}

# Request with:
#   X-Token: a
#   X-Token: b
# -> {"x_token": ["a", "b"]}
08

Внедрение зависимостей

Базовый Depends

Depends() внедряет возвращаемое значение функции в обработчик пути. Общая логика (пагинация, разбор, сессии БД) живёт в одном месте и переиспользуется в разных endpoint. Параметры зависимости тоже попадают в документацию OpenAPI.

fastapi
from fastapi import FastAPI, Depends

app = FastAPI()

def common_params(q: str | None = None, skip: int = 0, limit: int = 10):
    return {"q": q, "skip": skip, "limit": limit}

@app.get("/items")
def list_items(commons: dict = Depends(common_params)):
    return commons

@app.get("/users")
def list_users(commons: dict = Depends(common_params)):
    return commons

Зависимости-классы

Класс с __init__ может быть зависимостью: FastAPI вызывает его как функцию. Используйте Depends(CommonQueryParams) или сокращённое Depends(), когда параметр аннотирован классом. Внедряется экземпляр.

fastapi
from fastapi import FastAPI, Depends

class CommonQueryParams:
    def __init__(self, q: str | None = None, skip: int = 0, limit: int = 10):
        self.q = q
        self.skip = skip
        self.limit = limit

app = FastAPI()

@app.get("/items")
def list_items(commons: CommonQueryParams = Depends(CommonQueryParams)):
    return {"q": commons.q, "skip": commons.skip, "limit": commons.limit}

# shorthand: commons = Depends() infers the type

Вложенные зависимости

Зависимости сами могут зависеть от других зависимостей, образуя граф. FastAPI разрешает всё дерево, кеширует результат каждого в рамках запроса и пробрасывает исключения. Идеально для многоуровневой аутентификации (токен -> пользователь -> права).

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def get_token(authorization: str = Header()):
    if not authorization.startswith("Bearer "):
        raise HTTPException(status_code=401, detail="invalid header")
    return authorization.removeprefix("Bearer ")

def get_current_user(token: str = Depends(get_token)):
    if token != "admin-token":
        raise HTTPException(status_code=403, detail="forbidden")
    return {"username": "admin"}

app = FastAPI()

@app.get("/me")
def me(user: dict = Depends(get_current_user)):
    return user

Зависимости с yield (очистка)

Генератор-зависимость (yield) идеален для ресурсов, требующих очистки: сессии БД, файловые дескрипторы, транзакции. Код после yield выполняется как финализатор, даже если маршрут бросил исключение. В одной зависимости допускается только один yield.

fastapi
from fastapi import FastAPI, Depends

def get_db():
    db = open_db_session()       # acquire resource
    try:
        yield db                 # injected into the route
    finally:
        db.close()               # always runs after the request

app = FastAPI()

@app.get("/items")
def list_items(db = Depends(get_db)):
    return db.query("SELECT * FROM items")

Глобальные зависимости

Передайте dependencies=[...] в FastAPI() (или APIRouter), чтобы применять их на всех маршрутах без внедрения результата. Полезно для глобальной аутентификации, rate limiting и логирования запросов.

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def verify_token(x_token: str = Header()):
    if x_token != "supersecret":
        raise HTTPException(status_code=400, detail="X-Token missing")

def verify_key(x_key: str = Header()):
    if x_key != "realkey":
        raise HTTPException(status_code=400, detail="X-Key missing")

# applied to every route in the app
app = FastAPI(dependencies=[Depends(verify_token), Depends(verify_key)])

@app.get("/items")
def list_items():
    return [{"item": "a"}]   # token & key already checked

Зависимости для конкретного маршрута

Используйте dependencies=[Depends(...)] в декораторе (или APIRouter), чтобы потребовать зависимость для отдельных маршрутов без использования её результата. Так подписи маршрутов остаются чистыми, а проверки всё равно выполняются.

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def verify_token(x_token: str = Header()):
    if x_token != "secret":
        raise HTTPException(status_code=401, detail="bad token")

app = FastAPI()

@app.get("/public")
def public():
    return {"open": True}

@app.get("/private", dependencies=[Depends(verify_token)])
def private():
    return {"secret": "data"}
09

Безопасность (HTTPBasic / OAuth2 / JWT)

HTTP Basic Auth

HTTPBasic разбирает заголовок Authorization: Basic в имя пользователя и пароль. Используйте secrets.compare_digest (а не ==), чтобы предотвратить timing-атаки. Всегда возвращайте 401 с WWW-Authenticate: Basic, чтобы браузер запросил учётные данные.

fastapi
import secrets
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials

security = HTTPBasic()
app = FastAPI()

def get_current_user(credentials: HTTPBasicCredentials = Depends(security)):
    correct_user = secrets.compare_digest(credentials.username, "admin")
    correct_pass = secrets.compare_digest(credentials.password, "secret")
    if not (correct_user and correct_pass):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid credentials",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials.username

@app.get("/profile")
def profile(user: str = Depends(get_current_user)):
    return {"user": user}

OAuth2 Password Bearer

OAuth2PasswordBearer объявляет, что маршруты ждут Bearer-токен; зависимость извлекает его из заголовка Authorization. tokenUrl говорит интерфейсу документации, куда отправлять учётные данные. Сам токен — просто строка, пока вы его не проверите.

fastapi
from fastapi import FastAPI, Depends
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
app = FastAPI()

@app.get("/me")
def me(token: str = Depends(oauth2_scheme)):
    return {"token": token}

# client POSTs username+password to /token, receives an access token,
# then sends it as: Authorization: Bearer <token>

Создание JWT-токена

Используйте python-jose (или PyJWT) для подписи токенов. Утверждение 'sub' (subject) обычно хранит имя пользователя или id, а 'exp' задаёт срок действия. SECRET_KEY должен быть длинным, случайным и загружаться из окружения — никогда не коммитьте его.

fastapi
from datetime import datetime, timedelta, timezone
from jose import jwt

SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"

def create_access_token(data: dict, expires_minutes: int = 30) -> str:
    to_encode = data.copy()
    expire = datetime.now(timezone.utc) + timedelta(minutes=expires_minutes)
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

# token = create_access_token({"sub": "alice"})
# -> eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Декодирование JWT-токена

jwt.decode проверяет подпись и утверждение 'exp' автоматически, при неудаче бросая JWTError. Сопоставьте зависимость с 401 и WWW-Authenticate: Bearer, чтобы клиент знал о необходимости валидного токена.

fastapi
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import jwt, JWTError

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"

def get_current_user(token: str = Depends(oauth2_scheme)) -> str:
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str | None = payload.get("sub")
        if username is None:
            raise credentials_exception
        return username
    except JWTError:
        raise credentials_exception

credentials_exception = HTTPException(
    status_code=status.HTTP_401_UNAUTHORIZED,
    detail="Could not validate credentials",
    headers={"WWW-Authenticate": "Bearer"},
)

Хеширование паролей

Никогда не храните пароли в открытом виде. passlib с bcrypt (или argon2) выполняет соль и хеширование. verify() сравнивает открытый ввод с сохранённым хешем. pip install passlib[bcrypt] установит бэкенд bcrypt.

fastapi
from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def hash_password(plain: str) -> str:
    return pwd_context.hash(plain)

def verify_password(plain: str, hashed: str) -> bool:
    return pwd_context.verify(plain, hashed)

# usage when issuing tokens:
def authenticate_user(username: str, password: str):
    user = fake_db.get(username)
    if not user or not verify_password(password, user.hashed_password):
        return False
    return user

Поток входа OAuth2

OAuth2PasswordRequestForm читает имя пользователя и пароль из POST с form-encoding (стандартный password flow OAuth2). Возвращайте access_token и token_type: 'bearer'. Именно на этот endpoint указывает tokenUrl в OAuth2PasswordBearer.

fastapi
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm

app = FastAPI()

@app.post("/token")
def login(form: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(form.username, form.password)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
        )
    token = create_access_token({"sub": user.username})
    return {"access_token": token, "token_type": "bearer"}

# OAuth2PasswordRequestForm parses username+password from form data
# and powers the 'Authorize' button in the Swagger UI.
10

Middleware

Добавление middleware

@app.middleware('http') регистрирует функцию, оборачивающую каждый запрос. Она должна дождаться call_next(request), получить ответ, а затем может его проверить или изменить перед возвратом. Middleware работает для всех маршрутов.

fastapi
import time
from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def add_process_time(request: Request, call_next):
    start = time.perf_counter()
    response = await call_next(request)
    duration = time.perf_counter() - start
    response.headers["X-Process-Time"] = f"{duration:.4f}"
    return response

Middleware для своих заголовков

Middleware — правильное место для заголовков, которые должны быть в каждом ответе (заголовки безопасности, баннер сервера, ID трассировки). Меняйте объект ответа после ожидания call_next.

fastapi
from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def add_banner(request: Request, call_next):
    response = await call_next(request)
    response.headers["X-Powered-By"] = "FastAPI"
    response.headers["X-Frame-Options"] = "DENY"
    return response

# every response now carries these headers

BaseHTTPMiddleware

Для переиспользуемого настраиваемого middleware наследуйтесь от BaseHTTPMiddleware и регистрируйте через app.add_middleware(MyMiddleware, **options). Так же добавляются встроенные middleware CORS, GZip и TrustedHost.

fastapi
from starlette.middleware.base import BaseHTTPMiddleware
from fastapi import FastAPI, Request

class TimingMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        start = time.perf_counter()
        response = await call_next(request)
        response.headers["X-Duration"] = str(time.perf_counter() - start)
        return response

app = FastAPI()
app.add_middleware(TimingMiddleware)

# class-based middleware is reusable and configurable

Редирект на HTTPS

HTTPSRedirectMiddleware возвращает редирект 308 на HTTPS-версию любого HTTP-запроса. Используйте его за балансировщиком, который завершает TLS, чтобы гарантировать переход клиентов на защищённое соединение.

fastapi
from fastapi import FastAPI
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware

app = FastAPI()
app.add_middleware(HTTPSRedirectMiddleware)

# all HTTP requests are redirected to HTTPS (308)

Доверенные хосты

TrustedHostMiddleware отклоняет запросы, чей заголовок Host не входит в белый список, предотвращая атаки через подмену Host. Поддерживаются шаблоны вроде '*.example.com'. Всегда включайте 'localhost' для локальной разработки.

fastapi
from fastapi import FastAPI
from fastapi.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()
app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["example.com", "*.example.com", "localhost"],
)

# requests with a disallowed Host header get a 400 response

Порядок middleware

Starlette выполняет middleware в порядке LIFO для входящих запросов: последний добавленный работает первым. Добавляйте CORS рано (чтобы работал preflight), а GZip позже. Помните об этом, когда заголовок одного middleware не виден другому.

fastapi
from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Middleware runs in REVERSE order of registration for requests,
# and in registration order for responses.
app.add_middleware(GZipMiddleware, minimum_size=1000)
app.add_middleware(CORSMiddleware, allow_origins=["*"])

# request flow:  CORS -> GZip -> route
# response flow: route -> GZip -> CORS
11

CORS

Настройка CORSMiddleware

CORSMiddleware обрабатывает CORS preflight (OPTIONS) и добавляет заголовки Access-Control-*. allow_origins должен перечислять точные разрешённые источники; в production используйте список конкретных URL, а не ['*'].

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://example.com", "https://www.example.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/api/data")
def data():
    return {"data": 1}

Разрешить все источники (только для разработки)

allow_origins=['*'] разрешает любой источник, но не сочетается с allow_credentials=True (браузеры это отклоняют). Используйте только для полностью публичных API при разработке; в production перечисляйте реальные источники.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
    # allow_credentials=True CANNOT be combined with allow_origins=["*"]
)

Разрешить учётные данные

allow_credentials=True позволяет браузеру отправлять cookie и заголовки Authorization между источниками. Это требует конкретных источников (никогда '*'). Браузер ставит в ответах Access-Control-Allow-Credentials: true.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_credentials=True,    # send cookies / Authorization
    allow_methods=["GET", "POST"],
    allow_headers=["Authorization", "Content-Type"],
)

# needed when the frontend sends cookies or credentials with requests

Разрешённые методы и заголовки

allow_methods/allow_headers ограничивают, что браузер может отправить. expose_headers перечисляет заголовки ответа, которые разрешено читать фронтенд-JavaScript (иначе браузеры скрывают свои заголовки). Ответы preflight кешируются браузером.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
    allow_headers=["Authorization", "Content-Type", "X-Request-ID"],
    expose_headers=["X-Total-Count", "X-Process-Time"],
)

# expose_headers lets the frontend JS read these response headers

Preflight-запросы

Для «непростых» запросов (свои заголовки, PUT/DELETE, JSON content type) браузер отправляет preflight OPTIONS. CORSMiddleware перехватывает OPTIONS и отвечает разрешёнными методами и заголовками. max_age задаёт, как долго браузер кеширует этот ответ.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_methods=["*"],
    allow_headers=["*"],
    max_age=600,   # browser caches preflight result for 600s
)

# Browser sends OPTIONS preflight for non-simple requests;
# CORSMiddleware answers automatically with the right headers.

Динамическая проверка источников

Для динамических белых списков используйте allow_origin_regex (сопоставление с Origin запроса) вместо статического списка. Удобно, когда валидные источники следуют шаблону (например, любой поддомен example.com).

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

VALID_DOMAINS = {"example.com", "staging.example.com"}

def origin_check(origin: str) -> str | None:
    if origin and origin.replace("https://", "").replace("http://", "") in VALID_DOMAINS:
        return origin
    return None

app.add_middleware(
    CORSMiddleware,
    allow_origin_regex=r"https://.*\.example\.com",
    allow_methods=["*"],
    allow_headers=["*"],
)
12

Обработка исключений

Выброс HTTPException

raise HTTPException в любом месте маршрута или зависимости прерывает обработку и возвращает ответ с ошибкой. detail может быть строкой, словарём или списком — он становится полем JSON 'detail'. headers добавляет заголовки ответа.

fastapi
from fastapi import FastAPI, HTTPException, status

app = FastAPI()

items = {1: "Apple", 2: "Banana"}

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id not in items:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
            headers={"X-Error": "missing"},
        )
    return {"item": items[item_id]}

Своё исключение

Зарегистрируйте обработчик через @app.exception_handler(MyException), чтобы превратить своё исключение в HTTP-ответ. Обработчик получает запрос и исключение. Так централизуется формат ошибок предметной области.

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

class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name

app = FastAPI()

@app.exception_handler(UnicornException)
async def unicorn_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops, {exc.name} did it again"},
    )

@app.get("/unicorns/{name}")
def read_unicorn(name: str):
    if name == "yolo":
        raise UnicornException(name=name)
    return {"name": name}

Переопределение ошибки валидации

RequestValidationError возникает, когда ввод не проходит валидацию Pydantic. Переопределите его обработчик через @app.exception_handler(RequestValidationError), чтобы изменить форму ответа 422, например под общий формат ошибок компании.

fastapi
from fastapi import FastAPI, Request, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={
            "success": False,
            "errors": exc.errors(),
            "body": exc.body,
        },
    )

Переопределение обработчика HTTPException

Переопределите стандартный обработчик HTTPException, чтобы обеспечить единый JSON-формат ошибок для всех выброшенных HTTPException. При перепривязке обработчика импортируйте класс как fastapi.exceptions.HTTPException (тот же, что используется в raise).

fastapi
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse
from fastapi.exceptions import HTTPException as FastAPIHTTPException

app = FastAPI()

@app.exception_handler(FastAPIHTTPException)
async def custom_http_handler(request, exc: FastAPIHTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "success": False,
            "status": exc.status_code,
            "message": exc.detail,
        },
        headers=exc.headers,
    )

Частые коды состояния

Модуль status даёт именованные константы для всех HTTP-кодов, избавляя от магических чисел. 200 (по умолчанию для GET), 201 (создано), 204 (нет содержимого), 422 (ошибка валидации) — самые частые в приложениях FastAPI.

fastapi
from fastapi import FastAPI, status

app = FastAPI()

@app.get("/ok", status_code=status.HTTP_200_OK)
def ok(): return {"ok": True}

@app.post("/create", status_code=status.HTTP_201_CREATED)
def create(): return {"id": 1}

@app.get("/no-content", status_code=status.HTTP_204_NO_CONTENT)
def no_content(): return None

@app.get("/not-found")
def missing():
    # raise HTTPException(status.HTTP_404_NOT_FOUND, "nope")
    ...

# Other common: 400 BAD_REQUEST, 401 UNAUTHORIZED,
# 403 FORBIDDEN, 409 CONFLICT, 422 UNPROCESSABLE_ENTITY, 500 INTERNAL_SERVER_ERROR

Общий обработчик исключений

Обработчик для базового Exception перехватывает всё, что не обработано иначе, не давая трассировкам стека утекать клиентам. Всегда логируйте полную трассировку на сервере, а клиенту возвращайте общий 500.

fastapi
import logging
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

logger = logging.getLogger("uvicorn.error")
app = FastAPI()

@app.exception_handler(Exception)
async def unhandled(request: Request, exc: Exception):
    logger.exception("Unhandled error on %s", request.url.path)
    return JSONResponse(
        status_code=500,
        content={"detail": "Internal Server Error"},
    )

@app.get("/boom")
def boom():
    raise RuntimeError("something exploded")
13

Фоновые задачи

Основы BackgroundTasks

BackgroundTasks выполняет функции после отправки ответа — идеально для работы «отправил и забыл»: логирование, письма, инвалидация кеша. add_task планирует функцию (и аргументы), не блокируя ответ.

fastapi
from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def write_log(message: str):
    with open("log.txt", "a") as f:
        f.write(message + "\n")

@app.post("/send")
def send_notification(background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, "notification sent")
    return {"message": "notification queued"}

Несколько задач

Добавляйте сколько угодно задач: они выполняются последовательно в порядке добавления после возврата ответа. Так как они идут в том же процессе, держите их быстрыми и неблокирующими или переносите в настоящую очередь (Celery, RQ, Dramatiq).

fastapi
from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def send_email(to: str, subject: str): ...
def update_cache(key: str): ...
def notify_slack(msg: str): ...

@app.post("/signup")
def signup(background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email, "[email protected]", "Welcome")
    background_tasks.add_task(update_cache, "user_count")
    background_tasks.add_task(notify_slack, "new signup")
    return {"status": "ok"}

Задача с зависимостями

BackgroundTasks внедряется как любая зависимость. Функция задачи может получить значения (например, сессию БД), захваченные на момент запроса. Учтите, что ресурсы зависимостей с yield закрываются после завершения задач: задачи выполняются в рамках жизненного цикла запроса.

fastapi
from fastapi import FastAPI, BackgroundTasks, Depends

app = FastAPI()

def get_db_session():
    db = "session"
    yield db

def write_log(db, message: str):
    print(db, message)

@app.get("/items")
def list_items(background_tasks: BackgroundTasks, db = Depends(get_db_session)):
    background_tasks.add_task(write_log, db, "list called")
    return {"items": []}

Асинхронная функция задачи

Фоновые задачи могут быть синхронными (выполняются в пуле потоков) или асинхронными (ожидаются в цикле событий). Асинхронные задачи используйте для ввода-вывода через асинхронные библиотеки, синхронные — для CPU-нагрузки и блокирующей работы.

fastapi
from fastapi import FastAPI, BackgroundTasks
import httpx

app = FastAPI()

async def fetch_url(url: str):
    async with httpx.AsyncClient() as client:
        r = await client.get(url)
        return r.status_code

@app.post("/webhook")
def webhook(url: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(fetch_url, url)
    return {"queued": url}

Background против Celery

BackgroundTasks используйте для лёгкой некритичной работы, которой можно потерять при перезапуске. Для задач, которые должны переживать падения, повторяться и масштабироваться между машинами, берите настоящую очередь (Celery, RQ, Dramatiq, Arq) с брокером вроде Redis или RabbitMQ.

fastapi
# BackgroundTasks: in-process, no broker, lost if process crashes
@app.post("/quick")
def quick(tasks: BackgroundTasks):
    tasks.add_task(small_job)
    return {"ok": True}

# Celery/RQ/Dramatiq: separate workers, persistent, retryable
# from celery import Celery
# @celery.task
# def big_job(payload): ...
#
# @app.post("/heavy")
# def heavy(payload: dict):
#     big_job.delay(payload)
#     return {"queued": True}

Пример отправки письма

Отправка письма — классический сценарий BackgroundTasks: это медленно, и пользователь не должен ждать. Ответ возвращается сразу, а письмо уходит после. При большом объёме предпочитайте очередь и SDK почтового сервиса с повторами.

fastapi
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel, EmailStr

class Message(BaseModel):
    to: EmailStr
    subject: str
    body: str

app = FastAPI()

def send_email(to: str, subject: str, body: str):
    # smtplib or your provider's SDK
    import smtplib
    with smtplib.SMTP("localhost") as s:
        s.sendmail("[email protected]", to, f"Subject: {subject}\n\n{body}")

@app.post("/contact")
def contact(msg: Message, tasks: BackgroundTasks):
    tasks.add_task(send_email, msg.to, msg.subject, msg.body)
    return {"status": "queued", "to": msg.to}
14

WebSocket

Основы WebSocket

Используйте @app.websocket() для endpoint WebSocket. Нужно вызвать accept() до отправки и получения. Функция обычно зациклена на чтении сообщений; receive_text/receive_bytes/receive_json ожидают данные от клиента.

fastapi
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
    await ws.accept()
    while True:
        data = await ws.receive_text()
        await ws.send_text(f"echo: {data}")

# client (browser):
# const ws = new WebSocket("ws://localhost:8000/ws");
# ws.onmessage = (e) => console.log(e.data);

Отправка JSON

send_json() и receive_json() сами занимаются сериализацией, обмениваясь JSON-объектами через сокет. Для бинарных данных используйте send_bytes/receive_bytes. Каждая отправка и приём — отдельный фрейм WebSocket.

fastapi
import json
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    await ws.accept()
    while True:
        msg = await ws.receive_json()
        await ws.send_json({"reply": msg.get("text", "").upper()})

# send_text / send_bytes / send_json helpers are available

Закрытие WebSocket

WebSocketDisconnect возникает при закрытии соединения клиентом — ловите его для очистки. Для нормального закрытия вызывайте ws.close(code=1000); частые коды: 1000 (нормально), 1008 (нарушение политики), 1011 (ошибка сервера).

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

app = FastAPI()

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    await ws.accept()
    try:
        while True:
            data = await ws.receive_text()
            if data == "quit":
                await ws.close(code=1000)
                break
            await ws.send_text(data)
    except WebSocketDisconnect:
        print("client disconnected")

Менеджер соединений

ConnectionManager отслеживает активные сокеты, чтобы рассылать сообщения всем подключённым клиентам (например, в чате). Всегда удаляйте сокет при отключении, чтобы не отправлять в закрытые соединения и ограничивать память.

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

class ConnectionManager:
    def __init__(self):
        self.active: list[WebSocket] = []

    async def connect(self, ws: WebSocket):
        await ws.accept()
        self.active.append(ws)

    def disconnect(self, ws: WebSocket):
        self.active.remove(ws)

    async def broadcast(self, message: str):
        for ws in self.active:
            await ws.send_text(message)

manager = ConnectionManager()
app = FastAPI()

@app.websocket("/chat")
async def chat(ws: WebSocket):
    await manager.connect(ws)
    try:
        while True:
            msg = await ws.receive_text()
            await manager.broadcast(msg)
    except WebSocketDisconnect:
        manager.disconnect(ws)

Аутентификация WebSocket через query-параметр

Браузеры не могут задавать свои заголовки для WebSocket, поэтому токены аутентификации часто передают query-параметром (или через cookie). Проверьте данные до accept() и закрывайте с кодом 1008 (нарушение политики), если доступа нет.

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException

app = FastAPI()

async def authenticate(token: str) -> str:
    if token != "secret":
        raise HTTPException(status_code=401)
    return "alice"

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    token = ws.query_params.get("token")
    if not token:
        await ws.close(code=1008)
        return
    user = await authenticate(token)
    await ws.accept()
    try:
        while True:
            data = await ws.receive_text()
            await ws.send_text(f"{user}: {data}")
    except WebSocketDisconnect:
        pass

WebSocket с зависимостями

Зависимости можно использовать в WebSocket-endpoint так же, как в HTTP-маршрутах, но осмысленны только те, что читают данные начального рукопожатия (заголовки, query-параметры, cookie): тела запроса нет. Внедряйте их через Depends() как обычно.

fastapi
from fastapi import FastAPI, WebSocket, Depends, Header

app = FastAPI()

def token_validator(token: str = Header(default="")):
    # for WS, headers come from the initial HTTP handshake
    return token == "valid"

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket, valid: bool = Depends(token_validator)):
    if not valid:
        await ws.close(code=1008)
        return
    await ws.accept()
    while True:
        msg = await ws.receive_text()
        await ws.send_text(msg)
15

База данных (SQLAlchemy)

Настройка SQLAlchemy

create_engine настраивает пул соединений БД; SessionLocal — фабрика сессий; Base — декларативная база моделей. Для SQLite с FastAPI задайте check_same_thread=False, так как запросы могут выполняться в разных потоках.

fastapi
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

SQLALCHEMY_DATABASE_URL = "sqlite:///./app.db"
# postgresql: "postgresql://user:pass@localhost:5432/dbname"

engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    connect_args={"check_same_thread": False},  # sqlite only
)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
Base = declarative_base()

Зависимость сессии

Зависимость с yield — канонический способ выдавать сессию БД: каждый запрос получает свежую сессию, закрываемую в блоке finally. Это гарантирует очистку, даже если маршрут бросил исключение.

fastapi
from fastapi import Depends
from sqlalchemy.orm import Session

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.get("/items")
def list_items(db: Session = Depends(get_db)):
    return db.query(Item).all()

# each request gets its own session, closed automatically afterward

Определение модели

Описывайте таблицы как ORM-модели SQLAlchemy, наследуясь от Base. В production используйте Alembic для миграций схемы, а не create_all(). Колонки могут иметь индексы, допускать NULL и значения по умолчанию на уровне БД или Python.

fastapi
from sqlalchemy import Column, Integer, String, Boolean
from sqlalchemy.orm import declarative_base

Base = declarative_base()

class Item(Base):
    __tablename__ = "items"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True, nullable=False)
    price = Column(Integer, default=0)
    in_stock = Column(Boolean, default=True)

# create tables (for dev; use Alembic migrations in prod)
Base.metadata.create_all(bind=engine)

Создание записи

add() добавляет новую строку, commit() записывает её в БД, а refresh() перезагружает экземпляр с серверными значениями (например, автоинкрементным id). Оборачивайте несколько записей в транзакцию и коммитьте один раз в конце.

fastapi
from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session

app = FastAPI()

@app.post("/items", status_code=201)
def create_item(payload: ItemCreate, db: Session = Depends(get_db)):
    item = Item(name=payload.name, price=payload.price)
    db.add(item)
    db.commit()
    db.refresh(item)        # load generated id
    return item

Выборка записей

db.query(Model) начинает запрос; .filter() задаёт условия WHERE, .offset()/.limit() — пагинацию, .first() возвращает строку или None, .all() — список. Для простого равенства используйте .filter_by(name=x).

fastapi
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session

app = FastAPI()

@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
    return db.query(Item).offset(skip).limit(limit).all()

@app.get("/items/{item_id}")
def get_item(item_id: int, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    return item

Обновление и удаление

Для частичного обновления перебирайте model_dump(exclude_unset=True), чтобы менялись только переданные поля. delete() помечает на удаление; commit() применяет. При успешном DELETE возвращайте 204 No Content.

fastapi
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session

app = FastAPI()

@app.put("/items/{item_id}")
def update_item(item_id: int, payload: ItemUpdate, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    for k, v in payload.model_dump(exclude_unset=True).items():
        setattr(item, k, v)
    db.commit()
    db.refresh(item)
    return item

@app.delete("/items/{item_id}", status_code=204)
def delete_item(item_id: int, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if item:
        db.delete(item)
        db.commit()
16

База данных (Tortoise ORM)

Настройка Tortoise

Tortoise ORM асинхронен по своей природе и хорошо сочетается с FastAPI. Инициализируйте его при старте с db_url и модулями моделей. generate_schemas() годится для разработки; в production используйте Aerich для миграций. В новом коде применяйте lifespan вместо on_event.

fastapi
from fastapi import FastAPI
from tortoise import Tortoise

app = FastAPI()

async def init():
    await Tortoise.init(
        db_url="sqlite://db.sqlite3",
        modules={"models": ["app.models"]},
    )
    await Tortoise.generate_schemas()

@app.on_event("startup")
async def startup():
    await init()

@app.on_event("shutdown")
async def shutdown():
    await Tortoise.close_connections()

Определение модели

Модели Tortoise наследуются от Model и объявляют поля через tortoise.fields. Типы полей соответствуют типам колонок БД. Имя таблицы задаётся во вложенном классе Meta. Связи используют ForeignKeyField, ManyToManyField и т. д.

fastapi
from tortoise import fields
from tortoise.models import Model

class Item(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=100)
    price = fields.FloatField(default=0.0)
    created_at = fields.DatetimeField(auto_now_add=True)

    class Meta:
        table = "items"

    def __str__(self):
        return self.name

Создание записи

Item.create() — корутина, которая вставляет и возвращает новую строку. Чтобы вернуть ответ Pydantic, постройте BaseModel через from_tortoise_orm() (из tortoise.contrib.pydantic): так Tortoise корректно сериализует асинхронно загруженные связи.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel
from .models import Item

app = FastAPI()

class ItemIn(BaseModel):
    name: str
    price: float

@app.post("/items", response_model=ItemOut, status_code=201)
async def create_item(payload: ItemIn):
    item = await Item.create(name=payload.name, price=payload.price)
    return await ItemOut.from_tortoise_orm(item)

Асинхронная выборка

Запросы Tortoise ожидаются: .all() возвращает queryset, .filter() добавляет условия, .get_or_none() берёт одну строку или None, .first() — первое совпадение. Избегайте .get(), если не ждёте ровно одну строку (иначе исключение).

fastapi
from fastapi import FastAPI, HTTPException
from .models import Item

app = FastAPI()

@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10):
    return await Item.all().offset(skip).limit(limit)

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    item = await Item.get_or_none(id=item_id)
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    return item

Обновление и удаление

Измените атрибуты модели и вызовите await save(), чтобы обновить строку, или await Item.filter(id=...).update(name=x) для массового обновления. await item.delete() удаляет строку. Каждый метод — корутина, его нужно ожидать.

fastapi
from fastapi import FastAPI, HTTPException
from .models import Item

app = FastAPI()

@app.put("/items/{item_id}")
async def update_item(item_id: int, name: str):
    item = await Item.get_or_none(id=item_id)
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    item.name = name
    await item.save()
    return item

@app.delete("/items/{item_id}", status_code=204)
async def delete_item(item_id: int):
    item = await Item.get_or_none(id=item_id)
    if item:
        await item.delete()

Схемы Pydantic для Tortoise

tortoise.contrib.pydantic генерирует модели Pydantic прямо из моделей Tortoise, так что не нужно поддерживать две схемы. Используйте pydantic_model_creator для одного объекта и pydantic_queryset_creator для ответа-списка.

fastapi
from tortoise.contrib.pydantic import pydantic_model_creator, pydantic_queryset_creator
from .models import Item

ItemOut = pydantic_model_creator(Item, name="ItemOut")
ItemList = pydantic_queryset_creator(Item)

@app.get("/items", response_model=ItemList)
async def list_items():
    return await Item.all()

# auto-generates a Pydantic model from the Tortoise model,
# including types and docstrings.
17

Тестирование (TestClient)

Основы TestClient

TestClient оборачивает приложение и позволяет делать запросы в процессе (без реального сокета). Он основан на httpx и работает с pytest из коробки. Импортируйте тот же экземпляр app, что запускаете в production.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_root():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"Hello": "World"}

# TestClient is based on httpx; no network is involved —
# it calls the ASGI app directly in-process.

Тесты GET и POST

Передавайте json= для JSON-тела, params= для query-параметров, headers= для заголовков и files= для multipart-загрузок. Ошибки валидации дают 422 — проверяйте status_code и структуру 'detail' в ошибке.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_create_item():
    response = client.post(
        "/items",
        json={"name": "Apple", "price": 0.5},
    )
    assert response.status_code == 201
    assert response.json()["name"] == "Apple"

def test_validation_error():
    response = client.post("/items", json={"name": "Apple"})  # missing price
    assert response.status_code == 422

Фикстура pytest

Фикстура pytest, возвращающая TestClient, избавляет тесты от дублирования и даёт каждому тесту свежий клиент. Для тестов с БД добавьте фикстуру, которая создаёт и удаляет таблицы или откатывает транзакцию после каждого теста для изоляции.

fastapi
import pytest
from fastapi.testclient import TestClient
from main import app

@pytest.fixture
def client():
    return TestClient(app)

def test_read(client):
    r = client.get("/items")
    assert r.status_code == 200

def test_create(client):
    r = client.post("/items", json={"name": "X"})
    assert r.status_code == 201

# run: pytest -v

Подмена зависимостей

app.dependency_overrides заменяет зависимость (например, реальную сессию БД или аутентификацию) на мок или фейк во время тестов, не меняя маршруты. Это канонический способ тестировать endpoint в изоляции от внешних сервисов. Очищайте подмены после тестов.

fastapi
from fastapi.testclient import TestClient
from main import app, get_db

def get_test_db():
    # return a test session or mock
    yield FakeSession()

app.dependency_overrides[get_db] = get_test_db

client = TestClient(app)

def test_items():
    r = client.get("/items")
    assert r.status_code == 200

# restore afterwards:
app.dependency_overrides.clear()

Тестирование аутентификации

OAuth2PasswordRequestForm ожидает form-encoded данные (data=, а не json=). Используйте полученный токен в заголовке Authorization: Bearer для последующих защищённых запросов. Чтобы полностью обойти аутентификацию, подмените зависимость get_current_user.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def get_token():
    r = client.post(
        "/token",
        data={"username": "admin", "password": "secret"},
    )
    return r.json()["access_token"]

def test_protected():
    token = get_token()
    r = client.get(
        "/me",
        headers={"Authorization": f"Bearer {token}"},
    )
    assert r.status_code == 200
    assert r.json()["username"] == "admin"

Тестирование WebSocket

TestClient.websocket_connect() открывает WebSocket внутри менеджера контекста. Обменивайтесь сообщениями через send_text/receive_text (и варианты json/bytes). Приём на закрытом соединении бросает WebSocketDisconnect.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_websocket():
    with client.websocket_connect("/ws") as ws:
        ws.send_text("hello")
        data = ws.receive_text()
        assert data == "echo: hello"

def test_websocket_close():
    with client.websocket_connect("/ws") as ws:
        ws.send_text("quit")
        # the server closes the connection
18

Документация OpenAPI

Swagger UI

FastAPI автоматически генерирует интерактивный Swagger UI на /docs по вашим маршрутам, типам и docstring. Задайте title/description/version у приложения и добавьте docstring или summary/description к каждому маршруту, чтобы обогатить интерфейс.

fastapi
from fastapi import FastAPI

app = FastAPI(
    title="My API",
    description="Sample API with auto docs",
    version="1.0.0",
)

@app.get("/items", summary="List items", description="Returns all items")
def list_items():
    """Get every item in the catalog."""
    return [{"id": 1}]

# interactive docs at: http://localhost:8000/docs

ReDoc

ReDoc на /redoc — альтернатива Swagger только для чтения, ориентированная на документацию. Сырая схема OpenAPI доступна на /openapi.json и может передаваться другим инструментам. Отключить документацию можно через docs_url=None, redoc_url=None, openapi_url=None (например, в production).

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"hello": "world"}

# ReDoc (alternative docs UI) at: http://localhost:8000/redoc
# raw OpenAPI JSON at: http://localhost:8000/openapi.json

# disable docs entirely:
# app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)

Теги и группировка

Теги группируют маршруты в интерфейсе документации. Заранее объявите метаданные тегов (name, description, externalDocs) в openapi_tags, чтобы группа появилась ещё до использования. deprecated=True помечает endpoint устаревшим в документации.

fastapi
from fastapi import FastAPI

app = FastAPI(openapi_tags=[
    {"name": "users", "description": "User management"},
    {"name": "items", "description": "Item operations"},
])

@app.get("/users", tags=["users"])
def list_users(): ...

@app.post("/items", tags=["items"])
def create_item(): ...

@app.get("/items/{id}", tags=["items"], deprecated=True)
def get_item(id: int): ...

Метаданные маршрута

Декораторы принимают метаданные, попадающие в OpenAPI: summary (короткий заголовок), description (длинный текст), response_description, tags, deprecated и status_code. Docstring используется как description, если не передать его явно.

fastapi
from fastapi import FastAPI, status
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.post(
    "/items",
    response_model=Item,
    status_code=status.HTTP_201_CREATED,
    summary="Create an item",
    description="Creates a new item and returns it.",
    tags=["items"],
    response_description="The created item",
)
def create_item(item: Item):
    """Create endpoint docstring — also shown in docs."""
    return item

Примеры полей

Field(examples=[...]) и Body(examples=[...]) добавляют примеры в 'Try it out' Swagger UI и выпадающий список примеров. Примеры тела могут содержать несколько случаев с описаниями, показывая валидный и невалидный ввод.

fastapi
from pydantic import BaseModel, Field
from fastapi import FastAPI, Body

class Item(BaseModel):
    name: str = Field(examples=["Apple"])
    price: float = Field(examples=[0.5], gt=0)

app = FastAPI()

@app.post("/items")
def create_item(item: Item):
    return item

@app.post("/manual")
def manual(
    item: Item = Body(
        examples=[
            {"summary": "valid", "value": {"name": "Apple", "price": 0.5}},
            {"summary": "invalid", "value": {"name": "Apple", "price": -1}},
        ],
    ),
):
    return item

Своя схема OpenAPI

Переопределите app.openapi, чтобы изменить генерируемую схему: добавить логотип, лишние метаданные или убрать и преобразовать операции. Кешируйте результат в app.openapi_schema, чтобы схема генерировалась один раз. Именно её отдаёт /openapi.json.

fastapi
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    schema = get_openapi(
        title="Custom API",
        version="2.0.0",
        routes=app.routes,
    )
    schema["info"]["x-logo"] = {"url": "https://example.com/logo.png"}
    app.openapi_schema = schema
    return schema

app.openapi = custom_openapi
19

Развёртывание (Uvicorn / Gunicorn)

Uvicorn в production

В production запускайте Uvicorn за обратным прокси (Nginx, Caddy, облачный балансировщик). Используйте --proxy-headers, чтобы приложение видело реальный IP и хост клиента из X-Forwarded-For/X-Forwarded-Proto. Не используйте --reload в production.

fastapi
# Run directly with uvicorn (single worker)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1

# Recommended: behind a reverse proxy (nginx) on port 8000
# Use --proxy-headers so X-Forwarded-* is trusted
uvicorn main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips='*'

Gunicorn с воркерами Uvicorn

Gunicorn управляет несколькими процессами-воркерами Uvicorn: даёт плавную перезагрузку, перезапуск при падении и pre-fork масштабирование. Используйте класс UvicornWorker. Начните с числа воркеров (2 * число ядер + 1), затем измеряйте производительность.

fastapi
# install the uvicorn worker class
pip install "uvicorn[standard]" gunicorn

# run 4 worker processes managed by gunicorn
gunicorn main:app \
    -w 4 \
    -k uvicorn.workers.UvicornWorker \
    -b 0.0.0.0:8000 \
    --timeout 120

# -w workers (commonly 2*CPU+1), -k worker class

Развёртывание в Docker

Тонкий базовый образ Python уменьшает размер образа. Устанавливайте зависимости до копирования кода, чтобы использовать кеш слоёв Docker. Внутри контейнера запускайте воркеры gunicorn+uvicorn и откройте порт 8000 для хоста или оркестратора.

fastapi
# Dockerfile
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["gunicorn", "main:app", "-w", "4", \
     "-k", "uvicorn.workers.UvicornWorker", \
     "-b", "0.0.0.0:8000"]

# build & run:
# docker build -t myapi .
# docker run -p 8000:8000 myapi

Конфигурация окружения

pydantic-settings (ранее pydantic.BaseSettings) загружает конфигурацию из переменных окружения и файлов .env с проверкой типов. Так один и тот же образ работает в разных окружениях (dev/staging/prod), достаточно изменить переменные окружения.

fastapi
import os
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str = "sqlite:///./app.db"
    secret_key: str = "change-me"
    debug: bool = False
    allowed_origins: list[str] = ["http://localhost:3000"]

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

settings = Settings()

# .env file:
# DATABASE_URL=postgresql://user:pass@db:5432/app
# SECRET_KEY=long-random-string
# DEBUG=false

Обратный прокси Nginx

Nginx принимает HTTP(S) и передаёт на Uvicorn на localhost:8000. Задайте заголовки X-Forwarded-* (и используйте --proxy-headers в Uvicorn), чтобы приложение видело реальный IP и схему клиента. Строки Upgrade/Connection включают поддержку WebSocket.

fastapi
# /etc/nginx/conf.d/api.conf
server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;

        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Масштабирование и конкурентность

Масштабируйте двумя способами: больше воркеров Uvicorn на машине (CPU-нагрузка) и больше машин за балансировщиком (горизонтально). В асинхронных приложениях цикл событий обрабатывает много одновременных I/O-запросов на воркер. Добавьте endpoint /health, чтобы оркестраторы (k8s, ECS) проверяли живость.

fastapi
# Workers = process count (vertical scaling); pick ~2*CPU
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

# Inside async app: concurrency is cooperative via the event loop.
# CPU-bound work blocks it — offload to a threadpool or task queue.

# Horizontal scaling: run several containers behind a load balancer.
# Use a shared store (Redis) for session state and rate limits.

# Health check endpoint for the balancer:
@app.get("/health")
def health():
    return {"status": "ok"}
20

Продвинутые темы

События lifespan

Контекстный менеджер lifespan заменяет устаревшие обработчики on_event('startup'/'shutdown'). Код до yield выполняется при старте, после yield — при остановке, даже если старт не удался. Используйте его для инициализации подключений к БД, ML-моделей и кешей.

fastapi
from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    # runs at startup
    print("starting up")
    app.state.cache = {}
    yield
    # runs at shutdown
    print("shutting down")
    await app.state.cache.clear()

app = FastAPI(lifespan=lifespan)

# the old @app.on_event("startup") / "shutdown" are deprecated
# in favor of the lifespan handler above.

Подприложения (mount)

app.mount() присоединяет подприложение под префиксом пути — удобно для версионированных API или объединения нескольких приложений. У каждого подприложения свои маршруты и схема OpenAPI; документация родителя по умолчанию не включает маршруты дочернего.

fastapi
from fastapi import FastAPI

app = FastAPI()

api_v1 = FastAPI()
api_v2 = FastAPI()

@api_v1.get("/items")
def v1_items():
    return {"version": 1}

@api_v2.get("/items")
def v2_items():
    return {"version": 2}

app.mount("/v1", api_v1)
app.mount("/v2", api_v2)

# GET /v1/items -> {"version": 1}
# GET /v2/items -> {"version": 2}

APIRouter

APIRouter группирует связанные маршруты в модуль с общим префиксом, тегами, зависимостями и ответами. Подключайте через app.include_router(router) (при желании со своим префиксом или тегами). Это стандартный паттерн структурирования нетривиальных приложений.

fastapi
from fastapi import APIRouter, Depends

router = APIRouter(
    prefix="/items",
    tags=["items"],
    dependencies=[Depends(verify_token)],
    responses={404: {"description": "Not found"}},
)

@router.get("/")
def list_items():
    return []

@router.get("/{item_id}")
def get_item(item_id: int):
    return {"id": item_id}

# in main.py: app.include_router(router)

Статические файлы

StaticFiles отдаёт каталог статических ресурсов (изображения, CSS, JS) по URL-префиксу. Монтируйте его один раз на каталог. Для SPA-фронтендов смонтируйте финальный catch-all маршрут на index.html. Статические файлы обходят систему маршрутизации ради скорости.

fastapi
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

# serve files from ./static at /static
app.mount("/static", StaticFiles(directory="static"), name="static")

# /static/logo.png -> ./static/logo.png
# /static/css/app.css -> ./static/css/app.css

Потоковый ответ

StreamingResponse отправляет ответ, генерируемый частями (генератор или итератор), вместо сборки всего тела в памяти — идеально для больших экспортов CSV, потоковой передачи файлов и SSE. Задайте подходящий media_type, чтобы клиенты правильно обрабатывали поток.

fastapi
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import csv, io

app = FastAPI()

def iter_csv():
    output = io.StringIO()
    writer = csv.writer(output)
    writer.writerow(["id", "name"])
    for i in range(1000):
        writer.writerow([i, f"name-{i}"])
        yield output.getvalue()
        output.seek(0)
        output.truncate(0)

@app.get("/export.csv")
def export():
    return StreamingResponse(
        iter_csv(),
        media_type="text/csv",
        headers={"Content-Disposition": "attachment; filename=export.csv"},
    )

Свой класс маршрута

Наследование от APIRoute позволяет обернуть каждый обработчик своей логикой (логирование, трассировка, замеры времени), не трогая endpoint. Задайте app.router.route_class или передайте route_class в APIRouter. Обработчик выполняется для каждого подходящего запроса.

fastapi
from fastapi import FastAPI, Request, Response
from fastapi.routing import APIRoute
from typing import Callable

class LoggingRoute(APIRoute):
    def get_route_handler(self) -> Callable:
        original = super().get_route_handler()
        async def handler(request: Request) -> Response:
            print(f"-> {request.method} {request.url.path}")
            response = await original(request)
            print(f"<- {response.status_code}")
            return response
        return handler

app = FastAPI()
app.router.route_class = LoggingRoute

@app.get("/items")
def items():
    return {"items": []}

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.