Aiogram — библиотека для Telegram-ботов¶
Aiogram — асинхронная библиотека на языке Python для разработки ботов в мессенджере Telegram. Относится к классу клиентских обёрток над Telegram Bot API и распространяется по лицензии MIT. Название образовано от слов «AI» и «diogram» (от др.-греч. διάγραμμα — «схема, чертёж»), что отражает идею построения логики бота в виде схемы обработки событий.
¶Общая характеристика
Aiogram предоставляет программный интерфейс для взаимодействия с Telegram Bot API — серверным интерфейсом, через который сторонние программы отправляют сообщения, получают обновления и управляют чатами. Библиотека построена на асинхронной модели ввода-вывода и использует стандартный модуль asyncio, входящий в состав Python. Это позволяет одному процессу одновременно обслуживать множество пользователей без блокирующих задержек.
Ключевые характеристики:
- язык — Python (поддерживаются версии 3.8 и выше в актуальных релизах);
- модель — асинхронная, на основе
asyncio; - способ получения обновлений — длительный опрос (long polling) или вебхуки;
- лицензия — MIT;
- распространение — через репозиторий на GitHub и каталог пакетов PyPI.
¶История
Проект появился в 2019 году как развитие идей более ранних библиотек для Telegram на Python, в частности pyTelegramBotAPI и aiogram ранних версий. Автором и основным мейнтейнером выступил разработчик под псевдонимом Alex Root Junior. Библиотека быстро получила распространение в русскоязычном сообществе, поскольку документация и примеры изначально ориентировались на русский язык.
Значимым этапом стал выпуск ветки 2.x, закрепившей архитектуру с диспетчером, фильтрами и мидлварями. В 2023 году вышла версия 3.0, которая существенно переработала внутреннее устройство: изменилась система маршрутизации, появились сценарии (FSM-хранилища), обновился подход к работе с типами и сериализации. Переход с 2.x на 3.x потребовал от разработчиков переписывания части кода, что вызвало заметную дискуссию в сообществе.
¶Архитектура
Основу библиотеки составляют несколько взаимосвязанных компонентов.
¶Диспетчер
Dispatcher — центральный объект, принимающий обновления от Telegram и распределяющий их по обработчикам. Он хранит зарегистрированные хендлеры и определяет, какой из них должен сработать для конкретного события.
¶Роутеры
Router — механизм группировки обработчиков, введённый в версии 3.x. Роутеры позволяют разбивать логику бота на модули: например, отдельно обрабатывать команды администратора, отдельно — пользовательские сценарии. Роутеры могут вкладываться друг в друга, образуя иерархию.
¶Обработчики и фильтры
Обработчик (handler) — функция или корутина, вызываемая при наступлении события. Регистрация выполняется декораторами, например @router.message(). Фильтры (filters) определяют условия срабатывания: тип контента, наличие текста, совпадение с командой, соответствие регулярному выражению, членство в чате. Встроенные фильтры дополняются пользовательскими.
¶Машина состояний
Для многошаговых диалогов (анкеты, оформление заказа, пошаговая настройка) применяется конечный автомат — FSM (Finite State Machine). Состояния описываются через StatesGroup, а данные сохраняются в хранилищах: в памяти, в Redis, в SQL-базах. Это позволяет боту помнить контекст между сообщениями.
¶Middleware
Промежуточное программное обеспечение (middleware) встраивается в цепочку обработки события и позволяет выполнять сквозные задачи: логирование, проверку прав доступа, ограничение частоты запросов, подстановку данных в контекст.
¶Способы получения обновлений
| Способ | Описание | Применение |
|---|---|---|
| Long polling | Бот сам периодически запрашивает обновления у серверов Telegram | Разработка, небольшие проекты, отсутствие публичного домена |
| Вебхук | Telegram сам отправляет обновления на указанный HTTPS-адрес | Продакшен с постоянным доменом и сертификатом |
Вебхуки требуют наличия публичного адреса и поддержки TLS; для их обслуживания часто используют веб-фреймворки, например aiohttp или FastAPI, в связке с aiogram.
¶Применение
Aiogram используется для создания ботов различного назначения:
- информационные и справочные боты;
- боты интернет-магазинов с корзиной и оформлением заказа;
- службы поддержки и приёма заявок;
- боты-модераторы для групповых чатов;
- интеграционные боты, связывающие Telegram с внешними сервисами и базами данных;
- игровые и развлекательные боты.
Библиотека применяется как в личных проектах, так и в коммерческой разработке, где требуется асинхронная обработка большого числа одновременных запросов.
¶Экосистема
Вокруг aiogram сложилось сообщество, поддерживающее дополнительные инструменты. Среди них — сторонние библиотеки для работы с базами данных, готовые шаблоны проектов, генераторы клавиатур, средства развёртывания в контейнерах. Документация доступна на русском и английском языках, существуют тематические чаты и каналы для обмена опытом.
¶Критика и ограничения
К числу ограничений относят:
- привязку к возможностям Telegram Bot API, которые уже, чем у клиентских приложений;
- необходимость переписывать код при переходе между мажорными версиями;
- порог входа, связанный с пониманием асинхронного программирования;
- отсутствие официальной поддержки со стороны Telegram — библиотека развивается независимым сообществом.
Отдельно отмечается, что боты не могут писать пользователю первыми до начала диалога, а также ограничены в доступе к истории сообщений и ряду функций, доступных обычным аккаунтам.
¶Сравнение с альтернативами
Помимо aiogram, для разработки ботов на Python применяются pyTelegramBotAPI (синхронная модель, простой старт), python-telegram-bot (асинхронная и синхронная модели, развитая документация) и telethon (работа через клиентский API, а не Bot API). Aiogram выделяется сочетанием асинхронности, гибкой системы фильтров и роутеров, а также распространённостью в русскоязычной среде.
¶Источники
- Официальная документация aiogram.
- Репозиторий проекта на GitHub.
- Документация Telegram Bot API.
- Публикации и руководства по разработке Telegram-ботов на Python.