← вся теориятеория к собесу · FastAPI, Django и API

FastAPI и Pydantic

разбор писал Даниил, автор Сеньорчика

Зачем это спрашивают

FastAPI строит валидацию входа, фильтр ответа и OpenAPI-схему из одного источника: аннотаций типов и моделей Pydantic. На собесе проверяют, понимаешь ли ты, откуда это берётся и где FastAPI тебя не страхует. Ниже две программы на FastAPI 0.143 и Pydantic 2.14: модели на вход и выход и три эндпоинта с паузой под нагрузкой.

// Так спрашивают: «Как FastAPI валидирует вход?» «Зачем разные модели на вход и выход?» «Чем def-эндпоинт отличается от async def?» «Что будет, если вызвать блокирующую функцию в async def?»

Модель вместо проверок

FastAPI читает аннотации эндпоинта: параметр с типом модели Pydantic становится телом запроса, int в пути становится числом. UserCreate описывает вход, UserOut выход. Эндпоинт возвращает словарь, как вернула бы строку база, вместе с хешем пароля:

Строка "30" в поле age превратилась в число 30: по умолчанию Pydantic работает мягко и приводит то, что приводится без потерь. «тридцать» дал 422 с путём к полю и типом ошибки, и до кода эндпоинта запрос не дошёл. В строгом режиме (strict=True) та же строка "30" уже ошибка int_type. Из той же модели получилась OpenAPI-схема со списком обязательных полей, документацию отдельно писать не нужно.

response_model описывает ответ и заодно фильтрует его: password и hashed_password в UserOut нет, и наружу они не ушли. Поэтому модели входа и выхода разные, общая модель на оба направления рано или поздно отдаст пароль. И мелочь, которую любят спросить: изменяемый дефолт tags = [] в модели безопасен, каждый экземпляр получает свою копию списка, в отличие от аргумента функции def f(tags=[]).

from textwrap import wrap

from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, ConfigDict, ValidationError

app = FastAPI()


class UserCreate(BaseModel):  # что принимаем
    name: str
    age: int
    password: str


class UserOut(BaseModel):  # что отдаём
    id: int
    name: str
    age: int


@app.post("/users", response_model=UserOut, status_code=201)
def create(user: UserCreate):
    row = {"id": 1, **user.model_dump(), "hashed_password": "pbkdf2$600000$..."}
    return row  # так строку вернула бы база


client = TestClient(app)
for age in ("30", "тридцать"):
    r = client.post("/users", json={"name": "Анна", "age": age, "password": "qwerty"})
    print(r.status_code, r.json() if r.status_code == 201 else "")
    for err in r.json().get("detail", []) if r.status_code == 422 else []:
        print(" ", ".".join(map(str, err["loc"])), err["type"])
        print(*("   " + line for line in wrap(err["msg"], 38)), sep="\n")

schema = app.openapi()["components"]["schemas"]["UserCreate"]
print("required:", schema["required"])


class StrictAge(BaseModel):
    model_config = ConfigDict(strict=True)
    age: int


try:
    StrictAge(age="30")
except ValidationError as e:
    print("strict:", e.errors()[0]["type"])


class Tags(BaseModel):
    tags: list[str] = []


a, b = Tags(), Tags()
a.tags.append("vip")
print("у второй модели tags:", b.tags)

def или async def

Три эндпоинта ждут по секунде: async def с time.sleep, обычный def с time.sleep и async def с await asyncio.sleep. Uvicorn поднят в том же процессе. На каждый эндпоинт уходит десять запросов разом, а через 0.3 с ещё один запрос к /health:

async def выполняется прямо в цикле событий. time.sleep внутри него остановил весь цикл: десять запросов шли по очереди 10 секунд, и /health, которому ждать нечего, ответил через 9.8 секунды. Обычный def FastAPI отправляет в пул потоков, у AnyIO в нём по умолчанию 40 мест, и десять пауз прошли параллельно за секунду. await asyncio.sleep отдаёт цикл другим задачам, тоже секунда.

Отсюда правило: в async def только неблокирующие вызовы, вроде httpx.AsyncClient или asyncpg. Синхронную библиотеку зовут из обычного def или оборачивают в asyncio.to_thread. Тяжёлый расчёт на процессоре держит цикл так же, как sleep, и его выносят в отдельный процесс или очередь задач. Сделать все эндпоинты async def «для скорости» с синхронным драйвером базы значит получить первую строку вывода выше.

import asyncio
import threading
import time

import httpx
import uvicorn
from fastapi import FastAPI

app = FastAPI()


@app.get("/async-block")
async def async_block():
    time.sleep(1)  # блокирующий вызов прямо в цикле событий
    return {}


@app.get("/sync-block")
def sync_block():
    time.sleep(1)  # обычный def FastAPI уносит в пул потоков
    return {}


@app.get("/async-await")
async def async_await():
    await asyncio.sleep(1)  # ожидание отдаёт цикл другим запросам
    return {}


@app.get("/health")
async def health():
    return {}


async def late_health(client):
    await asyncio.sleep(0.3)  # пока идут тяжёлые запросы
    return (await client.get("/health")).elapsed.total_seconds()


async def burst(client, path):
    t0 = time.perf_counter()
    ping = asyncio.create_task(late_health(client))
    await asyncio.gather(*(client.get(path) for _ in range(10)))
    return time.perf_counter() - t0, await ping


async def main():
    async with httpx.AsyncClient(base_url="http://127.0.0.1:8001", timeout=60) as client:
        print("10 запросов разом, в каждом пауза 1 с")
        print("                      всё    /health")
        for path in ("/async-block", "/sync-block", "/async-await"):
            total, health = await burst(client, path)
            print(f"{path:<16} {total:6.1f} с {health:6.2f} с")


server = uvicorn.Server(uvicorn.Config(app, port=8001, log_level="warning"))
threading.Thread(target=server.run, daemon=True).start()
while not server.started:
    time.sleep(0.05)
asyncio.run(main())

Зависимости

Depends говорит FastAPI выполнить функцию до эндпоинта и подставить результат: сессию базы, текущего пользователя, параметры пагинации. Зависимость с yield отдаёт значение, а код после yield выполняется, когда запрос закончен: так закрывают сессию и возвращают соединение в пул. Если одну зависимость требуют несколько других, в пределах запроса она вычисляется один раз. Порядок и кэш зависимостей разобраны в главе про middleware.

Как отвечать: «Что будет, если вызвать блокирующую функцию в async def?»

Встанет весь цикл событий воркера, а с ним все запросы, которые он обслуживает. Я проверял на uvicorn: десять запросов к async def с time.sleep на секунду шли по очереди десять секунд, а простой /health ждал своей очереди почти столько же. Тот же код в обычном def FastAPI унёс в пул потоков, и все десять уложились в секунду, как и вариант с await asyncio.sleep. Поэтому в async def у меня только неблокирующие вызовы, синхронную библиотеку я оборачиваю в asyncio.to_thread или оставляю эндпоинт обычным def, а тяжёлый расчёт выношу в отдельный процесс.

Механизм, замер с соседним эндпоинтом и три способа обойти.

На чём валят

  • −Делают одну модель на вход и выход. Пароль уходит в ответ. UserCreate и UserOut.
  • −Вызывают блокирующую функцию в async def. Встаёт весь воркер. Обычный def или to_thread.
  • −Проверяют поля руками в эндпоинте. Дублируют Pydantic. Ограничения пишут в модели.
  • −Ждут, что строку "30" отвергнут. Мягкий режим приведёт её к числу. strict=True.
  • −Пишут все эндпоинты async def «для скорости». С синхронным драйвером это хуже def. Нужны async-библиотеки.

Проверь себя

Пять вопросов из банка по этой подтеме. Всего их 14, остальные разбираются в тренажёре.

  1. #fastapi_pydantic1 / 5
    Откуда FastAPI берёт валидацию тела запроса и сериализацию ответа?
    A)Из докстрингов эндпоинтов, парся их вручную
    B)Из аннотаций типов через Pydantic-модели
    C)Из middleware, проверяющего каждый запрос по схеме
    D)Из отдельного конфигурационного файла валидации проекта
    показать ответ и разбор
    +B)Из аннотаций типов через Pydantic-модели

    // разбор: FastAPI читает аннотации типов параметров и Pydantic-моделей: из них строит валидацию входа, сериализацию выхода и OpenAPI-схему. Источник правды один — тип. Объявил модель — получил проверку, приведение и доку без отдельного слоя валидации.

  2. #fastapi_pydantic2 / 5
    Зачем эндпоинту параметр response_model?
    A)Ускорить ответ за счёт заранее закэшированной модели
    B)Указать, какую таблицу вернуть клиенту напрямую
    C)Задать модель таблицы базы данных для эндпоинта
    D)Описать и отфильтровать форму ответа
    показать ответ и разбор
    +D)Описать и отфильтровать форму ответа

    // разбор: response_model валидирует и сериализует ответ по схеме и — важно — отбрасывает поля, которых в модели нет. Вернёшь объект с лишним password, а в модели его нет — клиент не увидит. Плюс корректная OpenAPI-схема ответа.

  3. #fastapi_pydantic3 / 5
    Поле объявлено age: int, в JSON пришло "age": "3" (строка). Что сделает Pydantic v2 (как в FastAPI)?
    A)Отклонит: строка это не int, даже если внутри число
    B)Приведёт к int 3 — числовая строка допустима
    C)Оставит значением строку '3' без приведения типа
    D)Молча подставит 0 как значение по умолчанию поля
    показать ответ и разбор
    +B)Приведёт к int 3 — числовая строка допустима

    // разбор: В нестрогом (lax) режиме, который FastAPI применяет к JSON, Pydantic v2 приводит числовую строку "3" к int 3. А вот "хай" вызовет ValidationError. Нужно запретить такие приведения — включай strict на поле или модели.

  4. #fastapi_pydantic4 / 5
    Что делает Depends(get_db) в сигнатуре эндпоинта FastAPI?
    A)Откладывает запуск эндпоинта до готовности соединения с БД
    B)Создаёт один глобальный синглтон соединения на приложение
    C)Резолвит зависимость и подставляет её результат
    D)Помечает этот параметр как необязательный в схеме
    показать ответ и разбор
    +C)Резолвит зависимость и подставляет её результат

    // разбор: Depends объявляет зависимость: FastAPI перед вызовом эндпоинта выполнит get_db, а результат подставит в параметр. Так инжектятся сессии БД, текущий пользователь, настройки. Зависимости кэшируются в пределах запроса и умеют цепляться друг за друга.

  5. #fastapi_pydantic5 / 5
    Эндпоинт объявлен обычным def (не async def). Как FastAPI его исполнит?
    A)Запустит в отдельном процессе через пул процессов
    B)Откажется запускать: путь-операции обязаны быть async
    C)В пуле потоков, чтобы не блокировать event loop
    D)Так же, как async — прямо в цикле событий приложения
    показать ответ и разбор
    +C)В пуле потоков, чтобы не блокировать event loop

    // разбор: FastAPI видит sync-функцию и уносит её в threadpool, чтобы возможный блокирующий код не заморозил event loop. async def исполняется прямо в цикле. Отсюда правило: блокирующий I/O без await безопаснее в обычном def, чем в async с блокировкой.

дальше

Теорию прочитал. Навык ставится повторением

В Сеньорчике эта подтема идёт в ежедневных сессиях: движок возвращает её, пока ответы не станут уверенными, и ведёт прогресс отдельно по каждой подтеме. Теория внутри тоже бесплатна, бесплатная часть практики — одна сессия дня в сутки.