aiogram 3: роутеры, FSM и мидлвари

aiogram - основной выбор для Python, и его сильная сторона не в отдельных возможностях, а в том, что он задаёт структуру, которая переживает рост бота.

Структура проекта

Порядок, который выдерживает рост:

• Точка входа. Создание объектов бота и диспетчера, подключение роутеров, запуск.
• Роутеры по смыслу. Каждый файл - одна область: регистрация, каталог, оплата, администрирование.
• Клавиатуры отдельно. Тексты кнопок в одном месте, а не разбросаны по обработчикам - см. кнопки.
• Работа с базой отдельно. Обработчик не должен содержать запросы.
• Тексты сообщений отдельно. Иначе правка формулировки превращается в поиск по всему проекту.
• Настройки из окружения. Токен и доступы не в коде - см. токен.

Главное правило: обработчик должен быть коротким. Он принимает событие, вызывает логику и отвечает. Если в обработчике двадцать строк бизнес-логики, её место в отдельном модуле.

Роутеры

Роутер - это группа обработчиков, которую подключают к диспетчеру целиком.

Что это даёт:

Порядок проверки. Обработчики проверяются в порядке подключения, и первый подошедший забирает событие. Это важно: обработчик «любое сообщение», подключённый раньше остальных, съест всё, и остальные не сработают никогда. Такой обработчик всегда идёт последним.

Локальные фильтры. Условие можно задать на весь роутер: например, весь административный роутер работает только для администраторов.

Точку для мидлварей. Мидлварь на роутере действует только на его обработчики.

Читаемость. Файл, отвечающий за оплату, содержит только оплату.

Состояния диалога

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

Практические правила:

Хранилище не в памяти процесса. Память подходит для разработки. В продакшене перезапуск потеряет все незавершённые диалоги, а перезапуск случается при каждом обновлении.

Всегда должен быть выход. Команда отмены, работающая из любого состояния. Пользователь, застрявший в сценарии без выхода, просто уходит.

Проверка ввода на каждом шаге. Пользователь отправит текст вместо числа, файл вместо текста и просто нажмёт кнопку из другого меню. Каждый шаг должен это переживать.

Не храните в состоянии много. Промежуточные данные - да, полноценные объекты - в базу.

Состояние истекает. Диалог, начатый неделю назад, продолжать бессмысленно.

Мидлвари

Мидлварь выполняется до и после обработчика. Туда выносят всё общее.

Что обычно живёт в мидлварях:

• Пользователь из базы. Один раз достали, обработчики получают готовым.
• Ограничение частоты. Защита от того, кто нажимает кнопку двадцать раз подряд.
• Логирование. Кто, что и когда сделал.
• Проверка прав. Особенно на административном роутере.
• Обработка ошибок. Единая реакция вместо копирования в каждый обработчик.
• Блокировка. Забаненный пользователь отсекается до логики.

Практический признак, что пора выносить в мидлварь: вы скопировали одну и ту же строку в третий обработчик.

Типовые ошибки

• Обработчик «любое сообщение» подключён рано. Съедает всё, остальные не срабатывают.
• Состояния в памяти в продакшене. Перезапуск теряет диалоги.
• Бизнес-логика в обработчиках. Тестировать невозможно, читать тяжело.
• Нет отмены. Пользователь застревает.
• Блокирующие вызовы в асинхронном коде. Синхронный запрос в базу или к внешнему API подвешивает весь бот, а не один диалог. Это специфичная для асинхронности ошибка, и на нагрузке она проявляется сразу.

Как это запускается и живёт на сервере - деплой и эксплуатация. Обзор - гид по Telegram-ботам.