Шаблон Telegram‑бота на Aiogram 3

Готовый к продакшену шаблон бота на Aiogram 3 с асинхронным стеком: SQLAlchemy 2 (async), Alembic, Redis FSM‑хранилище, Docker Compose (PostgreSQL, Redis, pgAdmin).

Стек

• Aiogram 3: роутеры, middlewares, FSM
• Redis: хранилище FSM (RedisStorage)
• PostgreSQL + SQLAlchemy 2 (async): работа с БД через async_sessionmaker
• Alembic: миграции БД
• Docker Compose: postgres, redis, pgadmin, bot

Быстрый старт

1. Скопируйте .env.example в .env и заполните значения.
2. Запустите все сервисы в Docker:

docker compose up --build

3. Примените миграции БД (в отдельном терминале из корня проекта):

alembic upgrade head

4. Бот стартует как контейнер bot автоматически. Для локального запуска без контейнера:

pip install -r requirements.txt
python -m app.main

Конфигурация (.env)

Используйте шаблон ./.env.example: скопируйте его в .env и задайте необходимые значения.

Важно:

• В Docker‑сценарии POSTGRES_HOST и REDIS_HOST для контейнера bot переопределяются на postgres и redis соответственно.

Архитектура и точки расширения

• app/main.py: точка входа (инициализация логирования, создание Bot, Dispatcher, пула сессий БД и запуск polling)
• app/factory/:
  • bot.py: setup_bot — инициализация бота
  • dispatcher.py: setup_dispatcher — FSM‑хранилище в Redis, middlewares, роутеры
  • runners.py: хуки старта/остановки, run_polling
  • db_session.py: создание пула сессий SQLAlchemy
• app/bot/:
  • handlers/: admin.py, user.py — хендлеры и роутеры
  • filters/: кастомные фильтры (например, AdminFilter)
  • middlewares/inner и middlewares/outer: троттлинг, прокидывание сессии БД
  • keyboards/, lexicon/, states/: клавиатуры, тексты, FSM‑состояния
• app/db/: фабрика пула, репозитории
• app/models/: декларативные модели SQLAlchemy
• migration/: Alembic (env настроен читать .env)

Логирование

Для настройки логирования используется файл logging.yml в корне проекта. Функция setup_logging() из модуля app.logging загружает конфигурацию из этого файла перед созданием любых логгеров:

from app.logging import setup_logging

# Инициализация логирования
setup_logging()

Если файл logging.yml не найден, выполняется logging.basicConfig с уровнем INFO по умолчанию.

Конфигурация logging.yml включает:

• консольный обработчик;
• ротацию лог-файла logs/app.log (10 МБ, 3 резервных копии);
• формат сообщений: %(asctime)s - %(name)s - %(levelname)s - %(message)s.

Убедитесь, что каталог logs существует и доступен для записи.

Работа с миграциями (Alembic)

• Сгенерировать новую миграцию:

alembic revision --autogenerate -m "init"

• Применить миграции:

alembic upgrade head

• Откатить:

alembic downgrade -1

Убедитесь, что .env доступен процессу, запускающему Alembic (в migration/env.py dsn собирается из переменных).

Запуск

• Полный стек в Docker:

docker compose up --build

• Только инфраструктура (БД, Redis, pgAdmin), а бот локально:

docker compose up -d postgres redis pgadmin
pip install -r requirements.txt
python -m app.main

Качество кода: линтинг, типизация, тесты и пре-коммиты

• Линтинг (Ruff):

  ruff check .
  ruff check . --fix      # автоисправление

• Форматирование (Ruff Format):

  ruff format .

• Проверка типов (MyPy):

  mypy app config

• Тесты (pytest) с покрытием:

  pytest -q                              # запуск тестов
  pytest --cov --cov-report=term-missing # отчёт покрытия в терминале
  pytest --cov --cov-report=html         # html-отчёт в ./htmlcov

• Pre-commit хуки:

  pip install -r requirements-dev.txt
  pre-commit install                   # установить git-хуки
  pre-commit run --all-files           # прогнать на всём репозитории

  В pre-commit включены: базовые проверки, Ruff (линт и формат), MyPy. Конфигурации берутся из pyproject.toml.

• Валидация commit message (Conventional Commits):

  • Сообщения коммитов должны соответствовать формату Conventional Commits (например: feat: add login, fix(auth): refresh token).
  • Хук commit-msg проверяет это автоматически при git commit.
  • Удобно создавать сообщения через мастер:

    cz commit

  • Примеры валидных сообщений:
    • feat: add user profile
    • fix(db): handle reconnect
    • refactor(core): simplify config loader
    • chore: bump dependencies

Полезные ссылки по коду

• Конфигурация: config/config.py
• Инициализация бота: app/factory/bot.py
• Диспетчер, FSM и middlewares: app/factory/dispatcher.py
• Хуки старта/остановки: app/factory/runners.py
• Точка входа: app/main.py

Траблшутинг

• «BOT_TOKEN must not be empty»: проверьте BOT_TOKEN в .env.
• Ошибки подключения к Redis: проверьте REDIS_HOST, REDIS_PORT, REDIS_PASSWORD; в Docker пароль обязателен (см. docker-compose.yml).
• Alembic не видит БД: убедитесь, что POSTGRES_* заданы и контейнер postgres в состоянии healthy.