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

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

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

Есть рабочая схема, которая переживает рост проекта:
• router — только HTTP-слой и коды ответов
• service — бизнес-правила и orchestration
• repository — запросы к БД и внешним источникам
• schemas — pydantic-модели для входа и выхода

Отдельно проверь зависимости. Если в каждом handler создаётся клиент, сессия или connection pool, приложение быстро теряет предсказуемость. В FastAPI лучше выносить это в dependency и управлять жизненным циклом через startup/shutdown или lifespan. Тогда тесты проще, а утечки ресурсов ловятся раньше 🔧

Ещё одна типовая ошибка — возвращать из endpoint «сырой» dict из глубины сервиса. Гораздо надёжнее держать явный response model: это фиксирует контракт, режет случайные поля и сразу показывает, где сломалась схема.

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