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

За FastAPI часто прячут одну и ту же ошибку: весь код уезжает в один роутер, а дальше проект начинает «пахнуть» сериализацией, SQL и бизнес-логикой одновременно. Через месяц такой сервис тяжело тестировать, а через три — страшно трогать.

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

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

И не экономьте на схемах ответа. Pydantic-модель — это не декоративная обёртка, а контракт. Если endpoint может вернуть три формы данных, лучше собрать их в явные модели, чем надеяться, что фронт «сам поймёт».

FastAPI хорошо живёт там, где у каждого слоя одна ответственность: тогда проект растёт без переписывания маршрутов каждые две недели.