Миграция бота Telegram между aiogram и pyTelegramBotAPI: пошаговое руководство

Вы когда-нибудь сталкивались с тем, что ваш Telegram-бот начал тормозить, ломаться при нагрузке или перестал поддерживаться? Это частая история. Многие начинают с pyTelegramBotAPI - он простой, документация понятная, и за пару часов можно запустить первого бота. Но со временем вы замечаете: код растёт, становится неподдерживаемым, а новые функции - вроде вебхуков, middleware, асинхронной обработки - требуют переписывания всего с нуля. Тогда вы слышите про aiogram: «он быстрее», «он современный», «он поддерживает асинхронность». Но как перейти? Неужели нужно всё переписать с нуля? Нет. И это не страшно.

Почему вообще менять фреймворк?

pyTelegramBotAPI - это синхронный фреймворк. Он работает как обычный Python-скрипт: один запрос - одна задача. Если ваш бот получает 10 сообщений одновременно, он обрабатывает их по очереди. Это нормально для бота с 100 пользователями. Но если вы выросли до 10 000 - вы начинаете терять сообщения, бот отвечает с задержкой, а пользователи жалуются. aiogram - асинхронный. Он обрабатывает десятки запросов одновременно, не блокируя другие. Это как заменить однополосную дорогу на шестиполосную магистраль.

Ещё один повод - поддержка. pyTelegramBotAPI не обновлялся серьёзно с 2022 года. Новые функции Telegram, такие как кнопки с запросами к API, инлайн-режим с кэшированием, или обработка голосовых сообщений - часто не поддерживаются или требуют костылей. aiogram, напротив, активно развивается. Версия 3.0 (вышедшая в 2024) добавила встроенную поддержку Telegram Bot API 7.0, включая новые типы сообщений и улучшенную маршрутизацию.

Что нужно знать перед миграцией

Перед тем как начать, убедитесь, что у вас есть:

• Полная копия текущего кода бота (сделайте бэкап в Git или просто скопируйте папку)
• Список всех используемых функций: обработчики сообщений, кнопки, инлайн-режим, callback-кнопки
• Данные подключения: токен бота, URL вебхука (если используете), база данных (SQLite, PostgreSQL, Redis)
• Понимание, какие части бота критичны - например, если у вас есть автоматическая рассылка по расписанию, это нужно перенести отдельно

Не пытайтесь мигрировать всё сразу. Начните с одного обработчика. Протестируйте его. Убедитесь, что он работает. Потом добавьте следующий. Так вы минимизируете риски.

Основные различия между aiogram и pyTelegramBotAPI

Вот ключевые отличия, которые нужно понять:

Самое важное - это синтаксис. В pyTelegramBotAPI вы пишете:

bot = telebot.TeleBot('TOKEN')

@bot.message_handler(commands=['start'])
def start(message):
    bot.send_message(message.chat.id, "Привет!")

В aiogram это выглядит так:

from aiogram import Bot, Dispatcher, Router
from aiogram.filters import Command

bot = Bot(token='TOKEN')
router = Router()

@router.message(Command("start"))
async def start(message: Message):
    await message.answer("Привет!")

Заметьте: await и Message в аннотациях. Это не просто синтаксис - это асинхронность. Без await ваш бот не будет работать. И если вы пропустите его - бот зависнет.

Пошаговая миграция: от pyTelegramBotAPI к aiogram

Вот как это сделать без катастрофы:

1. Установите aiogram: pip install aiogram. Удалите pyTelegramBotAPI только после полной проверки.
2. Создайте новый файл: bot_aiogram.py. Не переписывайте старый файл - сохраните его как резерв.
3. Скопируйте токен: вставьте его в новый файл. Не храните его в коде - используйте переменные окружения через .env и библиотеку python-dotenv.
4. Перенесите обработчики по одному: начните с команды /start. Перепишите его под aiogram. Запустите бота. Проверьте, отвечает ли он.
5. Перенесите callback-кнопки: в pyTelegramBotAPI вы используете callback_data и callback_query_handler. В aiogram это @router.callback_query. Синтаксис почти тот же, но с await.
6. Перенесите инлайн-режим: если у вас есть инлайн-запросы, в aiogram они обрабатываются через @router.inline_query. Там нужно возвращать InlineQueryResultArticle - это отличается от pyTelegramBotAPI, где вы просто возвращаете список.
7. Настройте вебхук: если вы раньше использовали polling, перейдите на вебхук. Это надёжнее. В aiogram это делается одной строкой: await bot.set_webhook(url="https://ваш-домен.рф/webhook"). Убедитесь, что у вас есть SSL-сертификат.
8. Перенесите базу данных: если вы использовали SQLite - ничего менять не нужно. Если использовали PostgreSQL - убедитесь, что подключение асинхронное. Используйте asyncpg вместо psycopg2.
9. Добавьте middleware: например, логирование. В aiogram это делается через router.message.middleware(). Вы можете логировать все сообщения, проверять права пользователя, кэшировать ответы - всё это встроено.
10. Тестируйте: запустите бота в тестовом режиме. Отправьте 50 сообщений подряд. Проверьте, не зависает ли он. Проверьте, не теряются ли кнопки.

Что может пойти не так

Вот типичные ошибки, с которыми сталкиваются:

• Пропущен await: это самая частая ошибка. Если вы пишете message.answer() без await - бот не отвечает, но и не выдаёт ошибку. Всё тихо ломается.
• Неправильные импорты: в aiogram есть from aiogram.types import Message. Если вы импортируете telebot.types.Message - будет ошибка.
• Смешивание синхронного и асинхронного кода: например, если вы используете requests.get() внутри асинхронного обработчика - это заблокирует весь бот. Используйте aiohttp или httpx вместо requests.
• Проблемы с вебхуком: если вы перешли на вебхук, но не настроили HTTPS - Telegram не будет отправлять запросы. Используйте ngrok для тестирования локально.
• Утерянные данные: если вы хранили состояние пользователей в переменных (например, user_state = {}) - это не работает в асинхронной среде. Используйте Redis или базу данных.

Что делать после миграции

После того как бот работает - не останавливайтесь.

• Добавьте логирование: записывайте все ошибки в файл. В aiogram можно использовать logging с форматом, который показывает chat_id, username, команду - это спасает при багах.
• Настройте мониторинг: используйте prometheus или просто отправляйте метрики в Telegram-канал, если бот упал.
• Обновите документацию: добавьте комментарии к новым обработчикам. Даже если вы один, через полгода вы забудете, как работает ваш код.
• Создайте CI/CD: автоматически деплойте бота при коммите в GitHub. Это сэкономит вам часы в будущем.

Стоит ли вообще мигрировать?

Если ваш бот работает, не ломается, и вы не планируете расти - оставьте как есть. Миграция требует времени. Но если вы видите, что:

• Бот начинает отвечать с задержкой
• Вы добавляете костыли, чтобы заставить его работать
• Вы хотите использовать новые функции Telegram (например, голосовые команды или оплату)
• Вы планируете масштабироваться до 10 000+ пользователей

- тогда миграция на aiogram не просто полезна - она необходима. Это не просто смена библиотеки. Это переход на современную архитектуру, которая позволит вашему боту расти вместе с вашим проектом.

Что дальше?

После миграции вы можете перейти к более сложным задачам:

• Использовать aiogram-dialog для создания многошаговых форм (например, регистрация пользователя)
• Подключить Redis для кэширования часто запрашиваемых данных
• Использовать YAML-конфиги для настройки бота - это удобнее, чем хардкодить параметры
• Добавить переводы через gettext - бот будет работать на нескольких языках

Миграция - это не конец. Это начало нового этапа. Вы не просто переписали код. Вы сделали его масштабируемым, надёжным и готовым к будущему.