Production-структура проекта на Aiogram 3: handlers, services и конфигурация

Надёжная структура Aiogram 3 отделяет Telegram-слой от бизнес-логики: handlers принимают обновление, services выполняют действие, repositories работают с данными, а config отвечает за окружение. Это упрощает тестирование и не даёт платежам, FSM и уведомлениям переплестись в одном файле.

Минимальная структура

app/
  bot.py
  config.py
  handlers/
    start.py
    orders.py
  services/
    orders.py
  repositories/
    orders.py
  keyboards/
  middlewares/
tests/

bot.py собирает приложение и подключает роутеры. В handler не нужно помещать SQL-запросы и сложные расчёты. Он должен достать входные данные, вызвать сервис и выбрать ответ пользователю.

Конфигурация через окружение

Токен и ключи интеграций не должны попадать в код или репозиторий. Минимальная конфигурация проверяет обязательные значения на старте:

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
    bot_token: str
    database_url: str = "sqlite+aiosqlite:///./bot.db"

В репозитории хранится только .env.example. Реальный .env добавляется на сервере или в секреты CI.

Роутеры вместо большого handler-файла

Группируй обработчики по предметной области: заявки, каталог, профиль, платежи. Роутер не должен знать, где физически хранится заявка. Это позволяет заменить SQLite на PostgreSQL без переписывания Telegram-слоя.

Services и repositories

Сервис отвечает на вопрос «что сделать», repository — «как прочитать или сохранить данные». Например, orders.create() проверяет бизнес-правила, а orders_repository.insert() выполняет запрос. Внешние API вызываются из отдельного gateway с timeout, повторными попытками и логированием request id.

Такой разнос особенно важен для оплаты. Webhook может прийти повторно, поэтому обработчик сначала проверяет idempotency key, затем обновляет заказ и только после этого выдаёт доступ.

Что проверить перед деплоем

• запуск проходит без ручного импорта из рабочей директории;
• .env.example описывает все переменные;
• polling и webhook не включены одновременно;
• ошибки внешних API не теряются в пустом except;
• повторный update не создаёт дубль заявки;
• есть health endpoint и понятный журнал событий;
• критические handlers покрыты тестами.

Для первого проекта можно начать с бесплатного практикума Aiogram 3, а затем перейти к полному курсу по Telegram-ботам, где есть платежи, Mini App, webhook, Docker и production-проверки.

Если нужна такая архитектура для реального продукта, опиши задачу в заявке: достаточно указать основной сценарий, интеграции и предполагаемую нагрузку.