FastAPI ломается не на роутинге, а на границах между входом, схемой и ответом

FastAPI ломается не на роутинге, а на границах между входом, схемой и ответом

За неделю в репах чаще всего всплывает один и тот же паттерн: эндпоинт работает, пока данные «идеальные». Как только приходит пустое поле, лишний ключ или неверный тип — начинают лететь 422, ручные if-ы и костыли в handler’ах.

Держите базовый чек-лист для живого проекта:
— вход валидируйте на уровне Pydantic-модели, а не внутри функции;
— бизнес-логику не смешивайте с зависимостями и запросом;
— response_model используйте всегда, иначе наружу легко утекут лишние поля;
— для async-операций не прячьте sync-код в endpoint без явного контроля.

Отдельная ловушка — зависимость, которая «просто достаёт объект из БД». Если она делает слишком много, тесты становятся хрупкими, а ошибки размазываются по стеку. Лучше, когда dependency отвечает только за получение контекста, а не за половину сценария.

Ещё один полезный фильтр: если endpoint нельзя объяснить одной фразой, его пора резать на сервисы. FastAPI хорошо переносит тонкие ручки и плохо переносит толстые контроллеры с логикой на 200 строк.

Если проект растёт, сначала наводите порядок на контрактах: вход, выход, зависимости. Потом уже оптимизируйте скорость разработки — иначе вы просто ускорите выпуск ошибок.