Создание Telegram‑бота Таро на Spring Boot

В последние годы мессенджеры стали площадкой не только для общения‚ но и для самых разных сервисов: от финансовых помощников до игр и гаданий. Одним из самых популярных направлений является теле‑гадание по картам Таро. В этой статье мы подробно разберём‚ как работает Telegram‑бот Таро‚ какие возможности он предоставляет‚ и как самостоятельно создать собственного бота на базе Spring Boot.

Содержание

Что такое Telegram‑бот Таро?
Почему именно Telegram?
Ключевые функции бота
Архитектура и стек технологий
Пошаговое создание бота
Развёртывание и поддержка
Безопасность и конфиденциальность
Перспективы развития

Что такое Telegram‑бот Таро?

Telegram‑бот Таро – это автоматизированный сервис‚ который позволяет пользователям получать расклады карт Таро прямо в чате Telegram. Пользователь выбирает тип расклада (например‚ «Кельтский крест»‚ «Три карты»)‚ а бот случайным образом вытягивает нужное количество карт‚ отправляет их изображения и предоставляет толкование каждой карты.

Пример готового проекта: taro-telegram-bot. Это простой бот‚ написанный на Spring Boot‚ который уже содержит набор изображений карт и их описания.

Кратко о репозитории

Язык: Java (Spring Boot)
Состояние: 0 звёзд‚ 1 наблюдатель‚ 0 форков
В репозитории есть готовые картинки карт и их толкования
Нет официальных релизов – проект находится в стадии «минимального рабочего прототипа»

Почему именно Telegram?

Широкая аудитория – более 700 млн активных пользователей по всему миру.
Простота интеграции – Telegram предоставляет удобный Bot API с поддержкой Webhook и Long Polling.
Кроссплатформенность – бот работает на смартфонах‚ планшетах и ПК без дополнительного клиентского кода.
Безопасность – сообщения шифруются‚ а токен бота хранится на сервере.
Гибкость UI – можно отправлять изображения‚ клавиатуры‚ инлайн‑кнопки и даже проводить интерактивные опросы.

Ключевые функции бота

Выбор расклада

Бот предлагает несколько популярных раскладов:

Три карты (прошлое‑настоящее‑будущее)
Кельтский крест (10 карт)
Одноразовое «Да/Нет»

Случайный подбор карт

Для каждого расклада бот использует java.util.Random (или более надёжный SecureRandom) и гарантирует‚ что одна и та же карта не будет вытянута дважды в одном раскладе.

Отправка изображений

Каждая карта хранится в виде PNG‑файла (пример: assets/cards/01_The_Fool.png). При формировании расклада бот отправляет изображения в порядке их появления.

Толкование карт

Текстовое описание (прямое и перевёрнутое) хранится в JSON‑файле cards.json. При необходимости бот выбирает нужный вариант в зависимости от ориентации карты.

Инлайн‑клавиатура

Пользователь может выбрать расклад‚ нажимая кнопки под сообщением‚ без необходимости ввода команд.

Локализация

В примере реализована поддержка русского языка‚ но структура позволяет добавить английскую‚ испанскую и другие локали.

Архитектура и стек технологий

Компонент	Технология	Назначение
Telegram Bot API	HTTP + JSON	Обмен сообщениями с пользователями
Spring Boot	Java 17+	Базовый фреймворк‚ упрощает конфигурацию и запуск
Spring WebFlux (опционально)	Reactive	Асинхронная обработка запросов‚ масштабируемость
Jackson	JSON парсер	Чтение файлов с толкованиями карт
Maven/Gradle	Система сборки	Управление зависимостями
Docker	Контейнеризация	Упрощённый деплой на любой сервер
GitHub Actions	CI/CD	Автоматическая сборка и публикация образа

Структура проекта


taro-telegram-bot/
├─ src/
│ ├─ main/
│ │ ├─ java/
│ │ │ └─ com.example.tarobot/
│ │ │ ├─ BotApplication.java
│ │ │ ├─ controller/
│ │ │ │ └─ TelegramUpdateController.java
│ │ │ ├─ service/
│ │ │ │ ├─ TarotService.java
│ │ │ │ └─ CardRepository.java
│ │ │ └─ model/
│ │ │ ├─ Card.java
│ │ │ └─ Spread.java
│ │ └─ resources/
│ │ ├─ application.yml
│ │ ├─ cards/
│ │ │ ├─ 01_The_Fool.png
│ │ │ └─ ... (78 карт)
│ │ └─ cards.json
└─ pom.xml

Пошаговое создание бота

Шаг 1. Регистрация бота в Telegram

Откройте чат с @BotFather.
Отправьте команду /newbot и следуйте инструкциям.
Сохраните полученный токен – он понадобится в конфигурации.

Шаг 2. Подготовка проекта

Создайте новый Spring Boot проект (можно через Spring Initializr) с зависимостями:

Spring Web
Spring Boot Actuator (для мониторинга)
Jackson (встроено в Spring Web)
Spring Boot DevTools (по желанию)

Шаг 3. Добавление зависимостей Telegram Bot API

В pom.xml добавьте библиотеку TelegramBots:

<dependency>
 <groupId>org.telegram</groupId>
 <artifactId>telegrambots-spring-boot-starter</artifactId>
 <version>6.5.0</version>
</dependency>

Шаг 4. Конфигурация токена

В src/main/resources/application.yml добавьте:

telegram:
 bot:
 username: your_bot_username
 token: ${TELEGRAM_BOT_TOKEN}

Токен лучше хранить в переменной окружения TELEGRAM_BOT_TOKEN для безопасности.

Шаг 5. Реализация модели карты

public class Card {
 private String name;
 private String imagePath;
 private String uprightMeaning;
 private String reversedMeaning;

 // getters & setters
}

Шаг 6. Хранилище карт (CardRepository)

Загружаем cards.json и создаём список карт в памяти:

@Service
public class CardRepository {
 private final List<Card> cards;

 public CardRepository(ObjectMapper mapper) throws IOException {
 InputStream is = getClass.getResourceAsStream("/cards/cards.json");
 Card[] array = mapper.readValue(is‚ Card[].class);
 this.cards = List.of(array);
 }

 public List<Card> getAll {
 return cards;
 }
}

Шаг 7. Сервис раскладов (TarotService)

@Service
public class TarotService {
 private final CardRepository repository;
 private final Random random = new SecureRandom;

 public TarotService(CardRepository repository) {
 this.repository = repository;
 }

 public List<Card> draw(int count) {
 List<Card> deck = new ArrayList<>(repository.getAll);
 Collections.shuffle(deck‚ random);
 return deck.subList(0‚ count);
 }
}

Шаг 8. Обработчик входящих сообщений

@Component
public class TelegramUpdateController extends TelegramLongPollingBot {

 private final TarotService tarotService;

 public TelegramUpdateController(TarotService tarotService‚
 @Value("${telegram.bot.username}") String username‚
 @Value("${telegram.bot.token}") String token) {
 super(token);
 this.setBotUsername(username);
 this.tarotService = tarotService;
 }

 @Override
 public void onUpdateReceived(Update update) {
 if (update.hasMessage && update.getMessage.hasText) {
 String text = update.getMessage.getText.trim.toLowerCase;
 Long chatId = update.getMessage.getChatId;

 switch (text) {
 case "/start":
 sendWelcome(chatId);
 break;
 case "три карты":
 sendSpread(chatId‚ 3);
 break;
 case "кельтский крест":
 sendSpread(chatId‚ 10);
 break;
 default:
 sendHelp(chatId);
 }
 }
 }

 private void sendWelcome(Long chatId) {
 SendMessage msg = new SendMessage(chatId.toString‚
 "Привет! Я Таро‑бот. Выбери расклад:
• Три карты
• Кельтский крест");
 executeSafely(msg);
 }

 private void sendHelp(Long chatId) {
 SendMessage msg = new SendMessage(chatId.toString‚
 "Я не понял команду. Напиши /start‚ чтобы увидеть варианты.");
 executeSafely(msg);
 }

 private void sendSpread(Long chatId‚ int count) {
 List<Card> drawn = tarotService.draw(count);
 for (Card card : drawn) {
 SendPhoto photo = new SendPhoto;
 photo.setChatId(chatId.toString);
 photo.setPhoto(new InputFile(new File("src/main/resources/cards/" + card.getImagePath)));
 photo.setCaption("" + card.getName + "
" + card.getUprightMeaning);
 photo.setParseMode(ParseMode.MARKDOWN);
 executeSafely(photo);
 }
 }

 private void executeSafely(BotApiMethod<?> method) {
 try {
 execute(method);
 } catch (TelegramApiException e) {
 // логируем ошибку
 e.printStackTrace;
 }
 }
}

Шаг 9. Тестирование локально

Запустите приложение: mvn spring-boot:run.
В Telegram найдите своего бота и отправьте /start.
Выберите расклад – бот должен отправить изображения и толкования;

Шаг 10. Подготовка к продакшн

Создайте Dockerfile:

FROM eclipse-temurin:17-jre
COPY target/taro-telegram-bot.jar app.jar
ENTRYPOINT ["java"‚"-jar"‚"/app.jar"]

Соберите образ: docker build -t taro-bot .
Запустите в облаке (AWS‚ GCP‚ DigitalOcean) с переменной TELEGRAM_BOT_TOKEN.

Развёртывание и поддержка

Webhook vs Long Polling

Для небольших проектов удобно использовать Long Polling‚ как в примере выше. При росте нагрузки рекомендуется переключиться на Webhook – Telegram будет отправлять POST‑запросы на ваш сервер‚ а вы сможете обрабатывать их в @RestController.

Мониторинг

Spring Boot Actuator позволяет следить за:

Статусом приложения (/actuator/health)
Метриками запросов (/actuator/metrics)
Логами (можно интегрировать с ELK‑стеком)

Обновление контента

Чтобы добавить новые карты или изменить толкования‚ достаточно обновить cards.json и перезапустить приложение. При желании можно реализовать динамическую загрузку из базы (PostgreSQL‚ MongoDB);

Безопасность и конфиденциальность

Токен бота хранится в переменной окружения‚ а не в репозитории.
Все пользовательские данные (чат‑ид‚ сообщения) не сохраняються‚ если нет необходимости в аналитике.
Если планируется хранить историю раскладов‚ используйте шифрование на уровне БД.
Для защиты от спама можно ограничить количество запросов от одного пользователя (rate‑limiting).

Перспективы развития

Поддержка нескольких языков – добавить файлы локализации (messages_ru.properties‚ messages_en.properties).
Интерактивные расклады – пользователь выбирает позиции карты по очереди‚ а бот задаёт вопросы.
Интеграция с AI – использовать GPT‑4 для генерации персонализированных рекомендаций на основе расклада.
Платные функции – расширенный анализ‚ личный гороскоп‚ архив раскладов.
Кроссплатформенные клиенты – веб‑интерфейс‚ мобильное приложение‚ интеграция с другими мессенджерами.

Telegram‑бот Таро – это отличный способ объединить древнее искусство гадания с современными технологиями. С помощью Spring Boot и готового репозитория вы можете быстро запустить собственный сервис‚ а дальнейшее развитие (AI‑подсказки‚ мульти‑язычность‚ платные функции) откроет новые возможности для монетизации и привлечения аудитории.

Помните‚ что главное в таком проекте – удобство пользователя и корректность толкований. Регулярно обновляйте базу карт‚ следите за отзывами и развивайте функционал‚ чтобы ваш бот оставался востребованным в мире онлайн‑гаданий.

Удачной разработки и вдохновения!