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 может сократить время на бойлерплейт и сосредоточить усилия на бизнес-логике. Библиотека молодая, но уже покрывает большинство типовых задач, с которыми сталкивается любой бот-разработчик.