Как я начинаю каждого Telegram-бота: структура проекта, которая не превращается в свалку

Папки с первого дня

Даже если бот маленький, раскладываю сразу так:

• bot.py: только запуск, больше ничего;
• handlers/: обработчики, по файлу на раздел (старт, заявки, админка);
• keyboards/: все кнопки в одном месте;
• db/: работа с базой;
• .env: токен и настройки.

Когда через полгода заказчик просит добавить раздел, я просто создаю новый файл в handlers и подключаю его. Ничего не ломается.

Токен никогда не в коде

Токен бота лежит в .env, а .env добавлен в .gitignore. Однажды увидеть свой токен в публичном репозитории и бегать его перевыпускать хватает, чтобы запомнить навсегда.

Роутеры вместо одного диспетчера

В aiogram 3 у каждого файла с обработчиками свой Router, а в bot.py они просто подключаются по очереди. Так сразу видно, какой раздел за что отвечает, а порядок подключения решает, какой обработчик сработает первым.

Анкеты через состояния

Если бот задаёт вопросы по очереди (имя, телефон, что нужно), это делается через FSM, машину состояний. Не надо хранить шаги в словарях и глобальных переменных, это первое, что ломается, когда пользователей становится больше одного.

Логи с первой строки

Подключаю logging сразу, ещё до первого обработчика. Когда клиент пишет «бот вчера вечером что-то не ответил», логи это единственный способ понять, что случилось.

Запуск на сервере

На VPS бот у меня работает как служба systemd с автоперезапуском. Сервер перезагрузился или бот упал, systemd поднимет его сам. Для большинства ботов хватает обычного polling, вебхук ставлю, когда нагрузка реально большая.

Сколько стоит такой бот под ключ, расписал в статье сколько стоит Telegram-бот.