Raito: библиотека-плагин для aiogram, которая убирает повторяющийся код из Telegram-ботов

Разработчик под ником Aidenable опубликовал на GitHub библиотеку Raito — плагин поверх aiogram3, который решает типовые задачи при разработке Telegram-ботов. Вместо того чтобы копировать одни и те же блоки кода между проектами, достаточно подключить одну зависимость.

Проект уже доступен с документацией на русском языке. Исходный код открыт: github.com/Aidenable/Raito.

Что конкретно добавляет Raito

Автор собрал в библиотеке функциональность, которой намеренно нет в aiogram — тот отвечает только за обёртку над Telegram Bot API. Raito берёт на себя всё остальное.

Hot-reload — пожалуй, самое востребованное улучшение. Раньше любое изменение кода требовало полного перезапуска бота. Теперь достаточно передать `production=False` при инициализации, и watchdog сам перезагрузит изменившиеся файлы.

Кастомные роутеры с приоритетами и динамической загрузкой. Можно задать `priority=9999` для хэндлеров со сложной фильтрацией или отключить автозагрузку роутера при старте (`autoload=False`) и включать его вручную командой `.rt load <name>` прямо из чата с ботом.

Автоматическая регистрация команд в слэш-меню. Достаточно пометить хэндлер декоратором `@rt.description("Описание")` — Raito сам соберёт список и передаст его в Telegram. Поддерживается i18n через `lazy_gettext`.

RBAC-роли из коробки. Система поддерживает встроенные роли `OWNER`, `ADMINISTRATOR`, `MODERATOR`, `DEVELOPER`, а также кастомные. Фильтрация в хэндлере выглядит лаконично:

```python @router.message(filters.Command("ban"), OWNER | ADMINISTRATOR | MODERATOR) async def ban(): ... ```

По умолчанию роли хранятся в памяти и сбрасываются при перезапуске. Для персистентности Raito предлагает JSONStorage, SQLiteStorage и PostgreSQLStorage — все три реализуют абстрактный класс `aiogram.BaseStorage`, поэтому их можно использовать и как основное хранилище FSM в самом aiogram.

Билдеры клавиатур в двух режимах. Статичный режим описывает разметку через вложенные списки строк — читается как таблица. Динамичный режим принимает параметры раскладки (`1, 2` — одна кнопка в первом ряду, две во втором) и строит клавиатуру через стандартный `InlineKeyboardBuilder`.

Пагинация, FSM-сцены и диалоги

Serverless-пагинация — одна из нетривиальных задач в боте. Большинство библиотек требуют внешнего хранилища. Raito обходится без него: состояние страницы кодируется прямо в `callback_data` по схеме `rt_p:<mode>:<name>:<page>:<total>:<limit>`, укладываясь в лимит Telegram в 64 символа.

Доступно пять режимов: `INLINE` (текст + inline-кнопки), `TEXT` (только текст с навигацией), `PHOTO` (медиа с подписью), `LIST` (текст в виде отформатированного списка) и `RICH` (новый формат rich-сообщений, требует aiogram ≥ 3.30.0).

FSM-сцены расширяют стандартный механизм aiogram: добавляется валидация данных через `SceneData` (Pydantic-модель) и явная навигация — `scene.next()`, `scene.retry()`, `scene.finish()`, `scene.goto()`. Это делает сложные анкеты и мастера настройки читаемыми и поддерживаемыми.

Диалоги (`wait_for`) — упрощённая альтернатива FSM для прототипов и ботов с низким DAU. Весь диалог описывается внутри одного хэндлера:

```python await message.answer("Enter username:") user = await raito.wait_for(state, F.text.regexp(r"@[\w]+")) ```

Автор честно предупреждает об ограничении: `wait_for` держит `asyncio.Future` и несовместим с `SimpleEventIsolation`. Для высоконагруженных ботов нужно использовать сцены.

Троттлинг настраивается как глобально для всего бота, так и на уровне отдельного хэндлера через `@rt.limiter(rate_limit=5.0, mode="user")`. Три режима: `user` (кулдаун на пользователя во всех чатах), `chat` (общий для чата) и `bot` (единый глобальный).

Как подключить

Инициализация занимает две строки поверх стандартного запуска бота:

```python raito = Raito(dispatcher, "src/handlers") await raito.setup() ```

Первый аргумент — диспетчер aiogram для dependency injection и регистрации роутеров. Второй — путь к папке с хэндлерами. Raito сканирует её автоматически, поэтому single-file архитектура не поддерживается: каждый роутер должен лежать в отдельном файле.

Для разработчиков, которые хотят получить доступ к `.rt`-командам (перезагрузка роутеров, управление ролями, список команд), достаточно передать свой Telegram ID: `Raito(developers=[12345678])`. Флаг `enable_dangerous_commands=True` дополнительно разблокирует `eval` и `bash` прямо из чата — удобно для отладки, но очевидно не для продакшена.

Lifespan-хуки реализованы в стиле FastAPI: всё до `yield` выполняется при старте, всё после — при остановке бота. Это удобно для регистрации команд, подключения к базе данных и graceful shutdown.

Для белорусских разработчиков, которые активно пишут Telegram-ботов для внутренних инструментов, автоматизации или как MVP-продукты, Raito может сократить время на бойлерплейт и сосредоточить усилия на бизнес-логике. Библиотека молодая, но уже покрывает большинство типовых задач, с которыми сталкивается любой бот-разработчик.

— По материалам Хабр / Разработка: оригинальная статья. Перевод и адаптация — редакция Digital Business.