aiogram 3.x: создание Telegram-ботов нового поколения

Введение в aiogram 3.x

aiogram — это популярная библиотека для разработки Telegram-ботов на Python. С выходом версии 3.0 произошли значительные изменения архитектуры: переход с асинхронного asyncio API к более современному подходу, основанному на FastAPI, и полная перестройка системы управления состояниями (FSM), фильтрами сообщений и middleware.

В этой статье рассмотрим ключевые концепции aiogram 3.x, необходимые для создания современных Telegram-ботов: работу с FSM из aiogram.fsm.storage, использование фильтров (filters), расширение функциональности через middleware, а также интеграцию бота с внешними API. Упор будет сделан на техническую реализацию без излишней абстракции.

Основы структуры проекта aiogram 3.x

В отличие от версии 2.x, где основной класс Bot и Dispatcher управляли всей логикой, в aiogram 3.x используется FastAPI-совместимый подход: бот регистрирует обработчики маршрутов (routes) через декораторы или вручную. Это позволяет легче интегрировать с другими API (например, REST), но требует более внимательного подхода к управлению состоянием.

Пример минимального бота:

dispatcher = Dispatcher()
app = FastAPI(routes=dispatcher.routes)
@dp.message()
def echo(message: Message):
    return message.text

Управление состояниями: FSM (Finite State Machine)

FSM в aiogram 3.x полностью переписан и теперь основан на ключ-значение хранилище (Storage). Вместо сложной иерархии состояний, как раньше, используется простая модель:

Пример использования FSM:

from aiogram.fsm.storage import RedisStorage
dispatcher.set_storage(RedisStorage.from_url('redis://localhost'))

@dp.message(IsCommandStart()) & StateFilter(None)
def start(message: Message):
    set_state = dp.current_state(user=message.from_user.id)
    return await set_state.set_state(State.PHONE)

Фильтры сообщений (filters)

Фильтры позволяют выполнять логику до обработки сообщения. Они реализуются как классы и могут проверять:

• Команды (commands)
• Текст (text, contains_text, is_command)
• Пользователей (UserFilter, ChatTypeFilter)
• Условия (lambda-filter)

Пример фильтра по типу чата:

def is_group_chat(message: Message):
    return message.chat.type == ChatType.GROUP
@dp.message(is_group_chat, IsCommandStart())
def start_in_group(message: Message):
    pass

Фильтры объединяются через логические операторы (&, |) и могут использоваться в декораторах обработчиков.

Middleware в aiogram 3.x

Middleware позволяет внедрять общую логику между обработчиками: авторизация, логирование, обработка ошибок. В aiogram 3.x middleware — это просто классы с методами pre_process, post_process и т.д., которые вызываются при каждом событии.

Пример middleware для логирования:

class LoggingMiddleware:
    async def pre_process(self, handler, data, *args):
        print(f'Before: {data.get("message")}')

async def post_process(handler, result, data, *args):
    if hasattr(result, 'text'): print('Sent:', result.text)

Интеграция с внешними API

Модульная структура aiogram 3.x позволяет легко интегрировать бота с другими сервисами. Например, при получении команды /weather можно:

1. Вызвать внешний API (например, OpenWeatherMap)
2. Обработать ответ и отправить пользователю

Пример работы с HTTP-клиентом httpx:

from httpx import AsyncClient
client = AsyncClient()
@dp.message(F.text == '/weather')
def handle_weather(message: Message):
    async with client:
        r = await client.get('https://api.openweathermap.org/data/2.5/weather', params={'q': 'Moscow'})
        if r.status_code == 200:
            return f'{r.json()["main"]["temp"]}°C'

Рекомендации по архитектуре проекта

При работе с aiogram 3.x рекомендуется:

• Разделять логику: обработка сообщений, бизнес-логика, работа с API — в разных модулях
• Использовать DI (инъекцию зависимостей) через FastAPI или Depends()
• Не хранить состояние на уровне обработчиков — использовать FSM и внешние хранилища
• Тестировать фильтры и middleware отдельно от основного кода

Заключение

aiogram 3.x предлагает более гибкую, модульную и масштабируемую основу для создания Telegram-ботов. Ключевые преимущества:

• Совместимость с FastAPI
• Упрощённая система FSM на основе ключей состояния
• Расширенный набор фильтров и middleware
• Поддержка асинхронных HTTP-запросов

Для разработки сложных ботов (например, CRM, чат-бота для поддержки клиентов) важно правильно использовать эти механизмы. При этом стоит помнить: aiogram 3.x — это инструмент, а не готовое решение.

Полезные ссылки

• Официальная документация aiogram
• Примеры FSM в репозитории проекта
• Сравнение версий 2.x и 3.0 (в блоге авторов)

Заключительный комментарий

В aiogram 3.x нет «волшебных» решений для всех задач, но есть мощные механизмы для точного контроля над поведением бота. При правильном применении — фильтры, FSM и middleware позволяют создавать сложные системы без дублирования кода.