FILE / ScuroNeko/Laniakea
README_RU.md
Исходный файл и его история в репозитории.
ScuroNeko
8618397bc1
add wiki links to README and README_RU fill Start here pages for setup, commands/plugins, and MsgContext add wiki page-priority tracker and local wiki AGENTS rules
253 lines
17 KiB
Markdown
253 lines
17 KiB
Markdown
# Laniakea
|
||
|
||
|
||
|
||
[](https://go.dev/)
|
||
[](LICENSE)
|
||
|
||
|
||
Легковесная, простая в использовании и производительная обёртка для Telegram Bot API на Go. Она упрощает разработку ботов благодаря чистой системе плагинов, поддержке Middleware, автоматической генерации команд и встроенному рейтлимитеру.
|
||
|
||
[English](README.md)
|
||
|
||
[Wiki](https://git.nix13.pw/ScuroNeko/Laniakea/wiki)
|
||
|
||
---
|
||
|
||
## ✨ Возможности
|
||
|
||
* **Простой и интуитивный API:** Разработан для лёгкости использования, основан на практических примерах.
|
||
* **Система плагинов:** Организуйте функциональность бота в независимые, переиспользуемые плагины.
|
||
* **Обработка команд:** Легко регистрируйте команды и извлекайте аргументы.
|
||
* **Поддержка промежуточных слоёв (Middleware):** Выполняйте код до или после команд (например, логирование, проверка доступа).
|
||
* **Автоматическая генерация команд:** Генерируйте справку и списки команд автоматически.
|
||
* **Встроенный ограничитель запросов (Rate Limiter):** Защитите бота от превышения лимитов Telegram API (с обработкой `retry_after`).
|
||
* **Контекст данных:** Передавайте свой контекст базы данных или состояния в обработчики.
|
||
* **Текучий интерфейс (Fluent Interface):** Стройте цепочки методов для чистой конфигурации (например, `bot.ErrorTemplate(...).AddPlugins(...)`).
|
||
|
||
---
|
||
|
||
## 📦 Установка
|
||
|
||
```bash
|
||
go get git.nix13.pw/scuroneko/laniakea
|
||
```
|
||
|
||
или
|
||
|
||
```bash
|
||
go get github.com/scuroneko/laniakea
|
||
```
|
||
|
||
## 🚀 Быстрый старт (с пошаговыми комментариями)
|
||
Вот минимальный пример бота "echo/ping" с подробными комментариями.
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"log"
|
||
|
||
"git.nix13.pw/scuroneko/laniakea" // Импортируем библиотеку Laniakea
|
||
)
|
||
|
||
// echo — это функция-обработчик команды.
|
||
// Она получает два параметра:
|
||
// - ctx: контекст сообщения (содержит информацию о сообщении, отправителе, чате и т.д.)
|
||
// - db: ваш пользовательский контекст базы данных (здесь мы используем NoDB — заглушку)
|
||
func echo(ctx *laniakea.MsgContext, db laniakea.NoDB) error {
|
||
// Отвечаем пользователю текстом, который он прислал, без префикса команды.
|
||
// ctx.Text содержит сообщение пользователя, из которого удалена часть с командой.
|
||
ctx.Answer(ctx.Text) // Ввод пользователя БЕЗ команды
|
||
return nil
|
||
}
|
||
|
||
func main() {
|
||
// 1. Создаём опции бота. Замените "TOKEN" на реальный токен от @BotFather.
|
||
opts := &laniakea.BotOpts{Token: "TOKEN"}
|
||
|
||
// 2. Инициализируем новый экземпляр бота.
|
||
// Используем laniakea.NoDB как тип контекста базы данных (база не нужна для примера).
|
||
bot, err := laniakea.NewBot[laniakea.NoDB](opts)
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
// Гарантируем освобождение ресурсов бота при выходе.
|
||
defer bot.Close()
|
||
|
||
// 3. Создаём новый плагин с именем "ping".
|
||
// Плагины помогают группировать связанные команды и промежуточные обработчики.
|
||
p := laniakea.NewPlugin[laniakea.NoDB]("ping")
|
||
|
||
// 4. Добавляем команду в плагин.
|
||
// p.NewCommand(echo, "echo") создаёт команду, которая вызывает функцию 'echo' по команде "/echo".
|
||
p.AddCommand(p.NewCommand(echo, "echo"))
|
||
|
||
// 5. Добавляем ещё одну команду, используя анонимную функцию (замыкание).
|
||
// Эта команда просто отвечает "Pong", когда пользователь отправляет "/ping".
|
||
p.AddCommand(p.NewCommand(func(ctx *laniakea.MsgContext, db laniakea.NoDB) error {
|
||
ctx.Answer("Pong")
|
||
return nil
|
||
}, "ping"))
|
||
|
||
// 6. Настраиваем бота: задаём шаблон ошибки и добавляем плагин.
|
||
// ErrorTemplate устанавливает формат для сообщений об ошибках (где %s будет заменён на текст ошибки).
|
||
// AddPlugins(p) регистрирует наш плагин "ping" в боте.
|
||
bot = bot.ErrorTemplate("Ошибка\n\n%s").AddPlugins(p)
|
||
|
||
// 7. Автоматически генерируем команды, такие как /start, /help и список всех зарегистрированных команд.
|
||
// Это необязательно, но очень полезно для большинства ботов.
|
||
if err := bot.AutoGenerateCommands(); err != nil {
|
||
log.Println(err)
|
||
}
|
||
|
||
// 8. Запускаем бота, начиная прослушивание обновлений (long polling).
|
||
if err := bot.Run(); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
}
|
||
```
|
||
|
||
### Как это работает
|
||
1. `BotOpts`: Содержит конфигурацию, например, токен API.
|
||
2. `NewBot[T]`: Создаёт экземпляр бота. Параметр типа T позволяет передать пользовательский контекст базы данных (например, *sql.DB), который будет доступен во всех обработчиках. Используйте laniakea.NoDB, если он не нужен.
|
||
3. `NewPlugin`: Создаёт логическую группу для команд и Middleware.
|
||
4. `AddCommand`: Регистрирует команду. Первый аргумент — функция-обработчик (`func(*MsgContext, T) error`), второй — имя команды (без слеша).
|
||
5. **Функции-обработчики**: Получают *MsgContext (детали сообщения, методы типа Answer) и ваш контекст базы данных T, а ошибку возвращают для централизованной обработки.
|
||
6. `ErrorTemplate`: Устанавливает шаблон для сообщений об ошибках. Плейсхолдер %s заменяется на текст ошибки.
|
||
7. `AutoGenerateCommands`: Регистрирует команды из плагинов в Telegram для поддерживаемых scope.
|
||
8. `Run()`: Запускает цикл опроса обновлений бота и возвращает ошибку, если старт или polling завершился неуспешно.
|
||
9. Экземпляр `Bot` одноразовый. После завершения `Run()` или `RunWithContext()` для следующего запуска создавайте новый бот.
|
||
|
||
## 📖 Основные концепции
|
||
### Плагины (Plugins)
|
||
Плагины — основной способ организации кода. Плагин может содержать несколько команд и Middleware.
|
||
|
||
```go
|
||
plugin := laniakea.NewPlugin[*MyDB]("admin")
|
||
plugin.AddCommand(plugin.NewCommand(banUser, "ban"))
|
||
bot.AddPlugins(plugin)
|
||
```
|
||
|
||
### Команды (Commands)
|
||
Команда — это функция, которая обрабатывает конкретную команду бота (например, /start).
|
||
|
||
```go
|
||
func myHandler(ctx *laniakea.MsgContext, db *MyDB) error {
|
||
// Доступ к аргументам команды через ctx.Args ([]string)
|
||
// Ответ пользователю: ctx.Answer("какой-то текст")
|
||
return nil
|
||
}
|
||
```
|
||
|
||
### Контекст сообщения (MsgContext)
|
||
Предоставляет доступ к входящему сообщению и полезные методы для ответа:
|
||
|
||
- `Answer(text string)`: Отправляет сообщение с parse_mode none.
|
||
- `AnswerLong(text string) []*AnswerMessage`: Разбивает длинный plain text на несколько сообщений.
|
||
- `AnswerMarkdown(text string)`: Отправляет сообщение, отформатированное MarkdownV2 (экранирование на вашей стороне).
|
||
- `Keyboard(text string, keyboard *InlineKeyboard) *AnswerMessage`: Отправляет сообщение с parse_mode none и Inline клавиатурой.
|
||
- `KeyboardLong(text string, keyboard *InlineKeyboard) []*AnswerMessage`: Разбивает длинный plain text на несколько сообщений и вешает клавиатуру на последний chunk.
|
||
- `KeyboardMarkdown(text string, keyboard *InlineKeyboard) *AnswerMessage`: Отправляет сообщение, отформатированное MarkdownV2 (экранирование на вашей стороне), и Inline клавиатурой.
|
||
- `AnswerPhoto(photoId, text string) *AnswerMessage`: Отправляет фотографию с подписью и parse_mode none.
|
||
- `AnswerPhotoMarkdown(photoId, text string) *AnswerMessage`: Отправляет фотографию с подписью, отформатированной MarkdownV2 (экранирование на вашей стороне).
|
||
- `EditCallback(text string)`: Редактирует сообщение с `parse_mode` none после нажатия inline-кнопки.
|
||
- `EditCallbackMarkdown(text string)`: Редактирует сообщение в формате MarkdownV2 (экранирование на вашей стороне) после нажатия inline-кнопки.
|
||
- `SendAction(action tgapi.ChatActionType)`: Отправляет действие "печатает", "загружает фото" и т.д.
|
||
- Поля: `Text`, `Args`, `From`, `FromID`, `Msg`, `InlineMsgId`, `CallbackQueryId` и другие.
|
||
- И много других методов и полей!
|
||
|
||
### Контекст базы данных (Database Context)
|
||
Параметр типа `T` в `NewBot[T]` — мощная функция. Вы можете передать любой тип, но для разделяемых зависимостей вроде пула соединений с БД обычно стоит использовать pointer type.
|
||
|
||
```go
|
||
type MyDB struct { /* ... */ }
|
||
db := &MyDB{...}
|
||
bot, err := laniakea.NewBot[*MyDB](opts)
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
bot.DatabaseContext(db)
|
||
```
|
||
|
||
### tgapi: API и Uploader
|
||
|
||
В `tgapi` есть два клиента:
|
||
|
||
- `API` для JSON-запросов (`SendMessage`, `EditMessageText`, методы с `file_id`/URL).
|
||
- `Uploader` для multipart-загрузок (`SendPhoto`, `SendDocument`, `SendVideo` с бинарными файлами).
|
||
|
||
Для продвинутых сценариев `tgapi.NewRequest(...)` и `tgapi.NewUploaderRequest(...)` остаются публичными low-level escape hatch API. Они менее безопасны, чем типизированные helper-методы: вызывающая сторона сама отвечает за корректное имя Telegram-метода и совместимые типы параметров/ответа.
|
||
|
||
## 🧩 Промежуточные слои (Middleware)
|
||
Middleware — это функции, которые выполняются перед обработчиком команды. Они идеально подходят для сквозных задач, таких как логирование, контроль доступа, ограничение скорости запросов или модификация контекста.
|
||
|
||
### Сигнатура
|
||
Функция middleware имеет ту же сигнатуру, что и обработчик команды, но должна возвращать bool:
|
||
|
||
```go
|
||
func(ctx *MsgContext, db T) bool
|
||
```
|
||
|
||
- Если возвращается true, выполняется следующий middleware (или сама команда).
|
||
- Если возвращается false, цепочка выполнения немедленно прерывается (команда не запускается).
|
||
|
||
### Добавление middleware
|
||
Используйте метод `AddMiddleware` плагина для добавления одной или нескольких функций middleware. Они выполняются в порядке добавления.
|
||
|
||
```go
|
||
plugin := laniakea.NewPlugin[*MyDB]("admin")
|
||
plugin.AddMiddleware(laniakea.NewMiddleware("logging", loggingMiddleware))
|
||
plugin.AddMiddleware(laniakea.NewMiddleware("admin-only", adminOnlyMiddleware))
|
||
plugin.AddCommand(plugin.NewCommand(banUser, "ban"))
|
||
```
|
||
|
||
### Примеры middleware
|
||
|
||
1. Логирующий middleware – логирует каждое выполнение команды.
|
||
```go
|
||
func loggingMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
|
||
log.Printf("Пользователь %d выполнил команду: %s", ctx.FromID, ctx.Msg.Text)
|
||
return true // продолжаем к следующему middleware/команде
|
||
}
|
||
```
|
||
|
||
2. Middleware только для администраторов – ограничивает доступ пользователям с определённой ролью.
|
||
```go
|
||
func adminOnlyMiddleware(ctx *laniakea.MsgContext, db *MyDB) bool {
|
||
if !db.IsAdmin(ctx.FromID) { // предполагается, что db имеет метод IsAdmin
|
||
ctx.Answer("⛔ Доступ запрещён. Только для администраторов.")
|
||
return false // останавливаем выполнение
|
||
}
|
||
return true
|
||
}
|
||
```
|
||
|
||
### Важные замечания
|
||
- Middleware может изменять MsgContext (например, добавлять пользовательские поля) перед запуском команды.
|
||
|
||
## ⚙️ Расширенная настройка
|
||
- **Инлайн-клавиатуры**: Создавайте клавиатуры с помощью `laniakea.NewInlineKeyboardJson`, `laniakea.NewInlineKeyboardBase64` или `laniakea.NewInlineKeyboard`. `Bot.SetPayloadType(...)` задаёт payload format по умолчанию, а `InlineKeyboard.SetPayloadType(...)` переопределяет его для конкретной клавиатуры.
|
||
- **Ограничение запросов**: Передайте настроенный `utils.RateLimiter` через `BotOpts` для корректной обработки лимитов Telegram.
|
||
- **Локализация**: `L10n` безопасен для конкурентного использования после подключения к боту.
|
||
- **Пользовательские update handlers**: Используйте `plugin.AddUpdateHandler(...)` для Telegram update types вне command/payload flow.
|
||
- **Жизненный цикл**: `RunWithContext(...)` не вызывает `Close()` автоматически. Завершайте бот явно и создавайте новый `Bot` для следующего запуска.
|
||
|
||
## Обработка Telegram Updates
|
||
- Команды и payload-ы обрабатываются через плагины.
|
||
- Для некомандных update-ов можно зарегистрировать обработчик через `plugin.AddUpdateHandler(updateType, handler)`.
|
||
- `message`, `channel_post` и `callback_query` остаются в command/payload flow.
|
||
- После JSON-декодирования `tgapi.Update` заполняет поле `Type`, чтобы обработчики могли явно видеть итоговый вид update.
|
||
|
||
## 📝 Лицензия
|
||
Этот проект лицензирован под GNU General Public License v3.0 - подробности см. в файле [LICENSE](LICENSE).
|
||
|
||
## 📚 Дополнительная информация
|
||
[GoDoc Laniakea](https://pkg.go.dev/git.nix13.pw/scuroneko/laniakea)
|
||
|
||
[Wiki](https://git.nix13.pw/ScuroNeko/Laniakea/wiki)
|
||
|
||
[Telegram Bot API](https://core.telegram.org/bots/api)
|
||
|
||
✅ Создано с ❤️ scuroneko
|