FastAPI ломается не на запросах, а на границах: где их проверить заранее

FastAPI ломается не на запросах, а на границах: где их проверить заранее

FastAPI любят за скорость разработки, но в проде чаще всего падают не роуты, а границы между слоями. Если сразу не отделить HTTP, домен и доступ к данным, то любой рефакторинг превращается в раскопки по всему проекту.

— В роуте держите только валидацию входа, вызов сервиса и формат ответа. Логику бизнес-правил туда не тащить.
— В Pydantic-моделях не прячьте поведение приложения: это контракт, а не место для сценариев.
— Сервисный слой должен быть независим от FastAPI, чтобы его можно было дернуть из теста, воркера или скрипта.
— Репозиторий отвечает за запросы к БД, а не за решение, можно ли вообще менять объект.

Еще одна типовая ошибка — смешивать async и sync без правил. Если внутри async-эндпоинта дергать блокирующий клиент, приложение формально работает, но под нагрузкой начинает «залипать». Для внешних API, БД и файловых операций заранее решите: либо везде async-стек, либо аккуратные sync-вставки через отдельные исполнители.

Тестируйте не эндпоинты по одному, а связки: схема → сервис → репозиторий. Тогда ловятся не только ошибки валидации, но и плохие границы между слоями. Хороший FastAPI-проект читается по структуре: роут тонкий, сервисы переиспользуемые, зависимости явные.