Представьте: вы решили написать Telegram-бота. Например, бота для приёма заказов, сбора заявок, автоматизации поддержки или уведомлений.
На старте всё выглядит просто. Вы пишете обработчик сообщений, подключаете webhook или polling — и бот уже отвечает пользователю.
Но через несколько дней появляются вопросы:
- где хранить пользователей
- нужно ли сохранять сообщения
- как понимать, почему бот упал
- как отслеживать ошибки
- какие события логировать
Именно здесь начинается архитектура бота.
Даже у простого Telegram-бота должна быть понятная структура хранения данных и логирования. Без этого проект быстро превращается в хаос: сложно искать ошибки, сложно анализировать поведение пользователей и сложно масштабировать систему.
В этой статье разберём:
- из каких частей состоит архитектура Telegram-бота
- какие данные обязательно хранить
- какие данные лучше не хранить
- какие события нужно логировать
- как организовать таблицы базы данных
- как устроить систему логирования
- типичные ошибки при разработке ботов
Базовая архитектура Telegram-бота
На самом деле архитектура простого бота довольно минималистична. Обычно она состоит из нескольких компонентов.
Компонент Назначение Telegram API принимает и отправляет сообщения Webhook или Polling доставка обновлений боту Backend-сервер обработка логики База данных хранение пользователей и состояния Логи диагностика и анализ ошибок
Простой поток работы выглядит так:
- Пользователь отправляет сообщение боту.
- Telegram отправляет update вашему серверу.
- Backend обрабатывает update.
- Бот выполняет действие (ответ, запись в БД и т.д.).
- Событие логируется.
Пример update от Telegram
{
"update_id": 123456,
"message": {
"message_id": 55,
"from": {
"id": 123456789,
"username": "alex"
},
"text": "/start"
}
}
Каждый update содержит информацию о пользователе, сообщении и событии.
Какие данные обязательно хранить
Многие начинающие разработчики пытаются сохранять всё подряд. Но на практике нужно хранить только данные, которые действительно используются в логике бота.
Основные сущности Telegram-бота
Сущность Зачем хранить Пользователь идентификация пользователя Чат тип диалога (личный, группа) Состояние пользователя этап сценария Действия пользователя история операций
Минимальный набор таблиц обычно выглядит так:
Таблица Назначение users информация о пользователях sessions текущее состояние сценария actions действия пользователя
Таблица пользователей
Эта таблица хранит информацию о людях, которые взаимодействуют с ботом.
Поле Описание id внутренний ID telegram_id ID пользователя в Telegram username username first_name имя created_at дата первого взаимодействия
Пример SQL-таблицы:
CREATE TABLE users (
id SERIAL PRIMARY KEY,
telegram_id BIGINT UNIQUE,
username TEXT,
first_name TEXT,
created_at TIMESTAMP
);
Почему важно хранить пользователя:
- можно отслеживать активность
- можно отправлять уведомления
- можно анализировать аудиторию бота.
Таблица состояния пользователя
Если бот содержит сценарии (например анкеты, меню, оформление заказа), нужно хранить текущее состояние пользователя.
Поле Назначение user_id пользователь state текущий этап payload дополнительные данные
Пример состояний:
Состояние Значение start пользователь только начал menu пользователь в главном меню order оформление заказа support обращение в поддержку
Это позволяет боту понимать контекст диалога.
Таблица действий пользователя
Иногда полезно сохранять действия пользователя для аналитики.
Поле Описание user_id пользователь action действие data данные created_at время
Например:
user_id action data 101 start /start 101 open_menu menu 101 order pizza
Такая таблица помогает анализировать поведение пользователей.
Какие данные не нужно хранить
Начинающие разработчики часто делают одну ошибку — сохраняют каждое сообщение пользователя.
Это почти всегда лишнее.
Telegram уже хранит историю сообщений, а в большинстве ботов эта информация не нужна.
Когда не стоит сохранять сообщения
Сценарий Нужно ли хранить простые команды нет меню-бот нет сервисный бот нет
Когда сообщения хранить полезно
Сценарий Причина поддержка пользователей история диалога CRM-бот анализ общения AI-бот обучение модели
Хранение всех сообщений увеличивает:
- нагрузку на базу
- сложность обработки данных
- стоимость инфраструктуры.
Что обязательно логировать
Логи — это основной инструмент диагностики.
Без логов невозможно понять:
- почему бот перестал отвечать
- почему webhook не работает
- где возникает ошибка.
Минимальный набор логов
Тип события Нужно ли логировать ошибки обязательно входящие updates желательно отправка сообщений желательно системные события желательно
Пример логирования update
logger.info("telegram update", {
update_id: update.update_id,
user_id: update.message?.from?.id
})
Это помогает отслеживать поток событий.
Логирование ошибок
Ошибки — самое важное, что нужно логировать.
Пример:
try {
await bot.sendMessage(chatId, text)
} catch (error) {
logger.error("telegram send error", {
chatId,
error: error.message
})
}
Без такого логирования отладка становится почти невозможной.
Хорошая схема логирования бота
Практика показывает, что достаточно трёх типов логов.
Тип логов Назначение info события системы warn подозрительные ситуации error ошибки
Пример структуры:
Тип Пример info пользователь нажал кнопку warn неизвестная команда error ошибка отправки сообщения
Типичная архитектура проекта бота
Хорошая структура проекта может выглядеть так.
Папка Назначение bot логика Telegram handlers обработчики команд services бизнес-логика database модели и запросы logs файлы логов
Такая структура делает проект понятным и поддерживаемым.
Типичные ошибки при разработке Telegram-ботов
Начинающие разработчики часто допускают одинаковые ошибки.
Сохранение всего подряд
Ошибка Почему плохо сохранение всех сообщений перегружает БД хранение лишних данных усложняет архитектуру
Отсутствие логирования
Ошибка Последствие нет логов невозможно отладить логирование только ошибок трудно анализировать события
Отсутствие состояния пользователя
Ошибка Последствие нет state-машины бот путается в сценариях
Как применять это через ИИ
AI-ассистенты могут сильно ускорить разработку Telegram-ботов.
Например, можно попросить модель сразу создать архитектуру.
Пример промта:
Я создаю Telegram-бота.
Нужно предложить архитектуру backend-проекта.
Условия:
- хранить пользователей
- хранить состояние сценария
- логировать ошибки и события
- использовать PostgreSQL
Покажи структуру таблиц и пример логирования.
Такой подход позволяет быстро получить основу проекта.
Итог
Архитектура Telegram-бота не должна быть сложной.
Но даже простой бот должен иметь понятную структуру хранения данных и логирования.
Минимальная архитектура выглядит так:
Компонент Назначение users хранение пользователей sessions состояние сценария actions действия пользователя logs диагностика системы
Если соблюдать эти принципы, бот будет:
- проще поддерживать
- легче масштабировать
- проще анализировать.