Russian | English

Описание

tnt-tg-bot - это библиотека, написанная на Lua для платформы Tarantool, которая предоставляет интерфейсы для работы с Telegram Bot API.

Note

Для production используёте последнюю из стабильных веток, или последний релиз.

В ветке master API может быть обновлён или быть частично совместимым с релизной версий.

Warning

В master ветку могут прилетать force push, hard reset и иногда ошибки.

Пользуйтесь стабильной веткой, либо последними релизами.

Особенности

• Простата и ясность интерфейсов
• Асинхронная обработка запросов
• Встроенная поддержка работы с платежами в Telegram Stars
• Встроенные методы для обработки команд, в том числе callback
• Вы сами даёте названия событиям, из коробки у вас только - bot.events.onGetUpdate(ctx)
• Простая работа с WebApp
• [TWA] Проверка валидности initData модулем - bot/init.lua
• [TWA] Реализованна поддержка ручек (routes)
• Поддержка аннотаций LDoc
• Большое колличество примеров

---

Оглавление

1. Showcase
2. Установка
3. Примеры
4. Структура
5. Интерфейсы
6. Рекомендации
7. Генерация документации

---

Showcase

• Niko Bot - Бот с мини играми, множеством команд, питомцами и модерацией групп
  Открыть скриншот

  
• Talking Hooligan - Популярный бот для чатов, присылает смешные и глупые сообщения

Установка

Автоматическая

1. Установите git, curl, lua 5.1 и luarocks.
2. (опционально) если нужна работа с WebApp:
   Потребуется установить rock пакет luaossl, для него в вашем дистрибутиве -
   установите заголовочные файлы для lua 5.1 и openssl.
3. Установите tarantool
4. Выполните скрипт автоматической установки необходимых пакетов

bash tnt-tg-bot.pre-build.sh

5. В случае проблем, перейти к ручной установки.

Note

Для успешной сборки luaossl - биндинга к OpenSSL, потребуются заголовочные файлы OpenSSL и Lua 5.1. В Ubuntu можно установить, выполнив sudo apt install libssl-dev liblua5.1-0-dev. luaossl нужен для работы модуля bot/libs/parseInitData.lua, модуль нужен для обработки данных веб Mini App. https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app

Ручная

1. Установите git, curl, lua 5.1 и luarocks.
2. Установите tarantool
3. (опционально) если нужна работа с WebApp:
   Потребуется установить rock пакет luaossl, для него в вашем дистрибутиве -
   установите заголовочные файлы для lua 5.1 и openssl.
4. Установка необходимых пакетов с помощью luarocks

• HTTP клиент/сервер (обязательно)

  luarocks install --local --tree=$PWD/.rocks --server=https://rocks.tarantool.org/ http

• Multipart Post обработчик (обязательно)

  luarocks install --local --tree=$PWD/.rocks --lua-version 5.1 lua-multipart-post 1.0-0

• Биндинг к openssl (опционально)

  luarocks install --local --tree=$PWD/.rocks --lua-version 5.1 luaossl

Примеры

• Observer pattern - Пример показывает реализацию паттерна наблюдателя, по факту - диспетчеризация событий. Так же пример хорошо структурирован, подходит что бы взять за основу
• Mini Shop - Пример минимального "магазина", показано как можно структурировать проект
• Star payments - Пример обработки платежей в звездах (покупка, возврат)
• examples/echo-bot-webhook.lua - Эхо-бот через WebHook
• examples/echo-bot-old.lua - Эхо-бот (старый API)
• examples/echo-bot.lua - Эхо-бот (новый API)
• examples/ping-pong.lua - Реакция на команду /ping
• examples/send-animation.lua - Отправка gif по команде /get_animation
• examples/send-document.lua - Отправка документа по команде /get_document
• examples/send-image.lua - Отправка изображения по команде /get_image
• examples/send-image-2.lua - Упрощенный пример отправки изображения через bot.sendImage
• examples/send-media-group.lua - Отправка группы медиа-файлов
• examples/simple-callback-old.lua - Пример обработки callback - /send_callback (старый API)
• examples/simple-callback.lua - Упрощенный пример обработки callback команд (новый API)
• examples/simple-process-commands.lua - Пример простого процессинга команд
• examples/routes-example/init.lua - Пример работы ручек в боте

Note

Рекомендуется использовать только новый API

Запуск примера

BOT_TOKEN - токен вашего бота

BOT_TOKEN="1348551682:AAFK3iZwBqEHwSrPKyi-hKyAtRgUwXrTiWW" tarantool examples/echo-bot.lua

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

• bot/init.lua - Точка входа
• bot/libs - Вспомогательные библиотеки
• bot/enums - Инамы
• bot/classes - Классы для объектов телеграмма
• bot/middlewares - Посредники
• bot/processes - Процессы (like runtime). Пример processCommand - процессинг команд
• bot/types - Модели/валидаторы для типов телеграмма
• bot/ext - Встроенные расширения (эддоны - фактически просто модули)
• bot/interfaces - Интерфейсы. На текущий момент в реализации паттерн observer

Интерфейсы

Метод	Описание	Пример использования
bot:cfg	Инициализация настроек	bot:cfg { token = "123468:foobarBAZ", username = "boobar_bot" }
bot.call	Выполнение запроса к Telegram API	bot.call('sendMessage', {chat_id = 123, text = 'Привет!'})
bot.events	Таблица с пользовательскими событиями	function bot.events.onPoll(ctx) ... end
bot.events.onGetUpdate	Событие обработки обновлений от Telegram	function bot.events.onGetUpdate(ctx) ... end
bot.sendImage	Упрощенная отправка картинки	examples/send-image-2.lua
bot.Command	Минимальный обработчик команд	bot.Command(ctx)
bot.CallbackCommand	Минимальный обработчик callback команд	bot.CallbackCommand(ctx)
bot:startWebHook	Запуск бота на удаленном сервере	Пример examples/echo-bot-webhook.lua
bot:startLongPolling	Запуск бота в режиме long polling	Любой пример из examples/*
bot:debugRoutes	Отладка ручек в режиме longPolling

По наличию аргументов см. ldoc - doc/index.html

Рекомендации

• Пользуетесь единым style guide, пример: lua-style-guide
• Исользуйте строгий режим

-- Блокирует попытку использовать необъявленную глобальную переменную
require('strict').on()

• Выстраивайте единую структуру проекта

┌─ app.lua                       - Точка входа
├── bot                          - Библиотека tnt-tg-bot
├── pre-build.sh                 - Скрипт установки необходимых зависимостей
├── conf                         - Конфиги
├── bin                          - Скрипты: для запуска, для линтера, ...
├── src                          - Основная директория бота
│   ├── classes                  - Классы
│   ├── enums                    - Инамы
│   ├── events                   - События для onGetUpdate
│   ├── commands                 - Разделённые по типам команды
│   │   ├── maintenance          - Директория для команд режима обслуживания
│   │   └── private              - Директория для команд, которые работают только в ЛС с ботом
│   │   └── public               - Директория для публичных команд (чаты, супергруппы, ...)
│   │   └── commandLoader.lua    - Единый загрузчик команд (команды лучше всего загружать в `bot.commands`)
│   ├── models                   - Модели для представления объектов из/в хранилище
│   ├── processes                - Процессы и рантаймы
│   │   └── processCommand.lua   - Единый обработчик команд 
│   ├── routes                   - Директория с ручками API
│   ├── services                 - Сервисы реализующие CRUD логику
│   ├── spaces                   - Схемы спейсов
│   └── utils                    - Отдельные утилиты
└── var                          - Системная директория
    ├── log                      - Директория для логов бота
    └── storage                  - Директория хранилища 
        ├── snap
        └── xlog

Генерация документации

bash bin/ldoc

Вклад в проект

Через форк репозитория и открытия Pull Request