Wiki
猫Table of Contents
- Getting Started RU
- Что нужно сначала
- Самый маленький полезный бот
- Что важно понять сразу
- 1. NewBot[T] использует generic-параметр зависимости
- 2. Команды живут внутри плагинов
- 3. Хендлеры возвращают error
- 4. Bot single-use
- 5. Close() все равно нужен
- Рекомендуемый порядок старта
- Частые ошибки на старте
- Нет токена
- Нет плагинов
- Неожидание, что ctx.Text уже очищен от команды
- Использование value types для shared state
- Куда идти дальше
Getting Started RU
English version: Getting-Started
Начни с этой страницы, если ты впервые подключаешь Laniakea к новому боту. Это сокращенная русскоязычная версия старта. Полная и наиболее актуальная страница: Getting-Started.
Что нужно сначала
- Go 1.26 или новее
- токен Telegram-бота от
@BotFather - Go-модуль, который может импортировать
git.scuroneko.dev/scuroneko/laniakea
Установка:
go get git.scuroneko.dev/scuroneko/laniakea
или:
go get github.com/scuroneko/laniakea
Самый маленький полезный бот
package main
import (
"log"
"git.scuroneko.dev/scuroneko/laniakea"
)
func ping(ctx *laniakea.MessageContext, db laniakea.NoData) error {
ctx.Answer("Pong")
return nil
}
func main() {
bot, err := laniakea.NewBot[laniakea.NoData](&laniakea.BotOpts{
Token: "TOKEN",
})
if err != nil {
log.Fatal(err)
}
defer bot.Close()
plugin := laniakea.NewPlugin[laniakea.NoData]("main")
plugin.Command("ping", ping)
bot.AddPlugins(plugin)
if err := bot.Run(); err != nil {
log.Fatal(err)
}
}
Если пользователь отправит /ping, бот ответит Pong.
Что важно понять сразу
1. NewBot[T] использует generic-параметр зависимости
Параметр T — это общий контекст зависимостей, который попадает в хендлеры, middleware и runners.
Используй:
laniakea.NoData, если dependency injection не нужен- pointer type, например
*sql.DB,*Storeили*App, если нужен общий state
Пример:
type App struct {
Users *sql.DB
}
app := &App{Users: db}
bot, err := laniakea.NewBot[*App](opts)
if err != nil {
return err
}
bot.SetAppData(app)
2. Команды живут внутри плагинов
Обычный путь такой:
- создать
Bot - создать
Plugin - добавить команды в
Plugin - зарегистрировать
PluginчерезAddPlugins(...)
Пример:
plugin := laniakea.NewPlugin[laniakea.NoData]("admin")
plugin.Command("ping", ping)
bot.AddPlugins(plugin)
Подробности: Commands-and-Plugins
3. Хендлеры возвращают error
Сигнатура хендлера:
func(ctx *laniakea.MessageContext, db T) error
То есть:
- на успехе возвращай
nil - если хочешь централизованный поток обработки ошибок, возвращай
error
Пример:
func profile(ctx *laniakea.MessageContext, db *App) error {
user, err := db.LoadUser(ctx.FromID)
if err != nil {
return err
}
ctx.Answerf("Hello, %s", user.Name)
return nil
}
Подробности: Error-Handling
4. Bot single-use
После Run(), RunWithContext(...) или RunWebhookWithContext(...) нельзя снова запускать тот же экземпляр Bot.
Правильная модель:
- создать bot
- настроить
- запустить один раз
- закрыть
- создать новый bot для следующего запуска
После завершения не надо повторно вызывать никакой runtime entry point на том же экземпляре.
Подробности: Bot-Lifecycle
5. Close() все равно нужен
Даже если ты используешь Run(), RunWithContext(...) или RunWebhookWithContext(...), ресурсы нужно закрывать явно:
defer bot.Close()
Рекомендуемый порядок старта
Для большинства ботов удобнее всего такой порядок:
- Собрать
BotOpts - Вызвать
NewBot[T](opts) - Подключить database context, localization и другие настройки
- Создать плагины
- Добавить команды, payloads и middleware в плагины
- Зарегистрировать плагины через
AddPlugins(...) - При необходимости вызвать
AutoGenerateCommands() - Вызвать
Run(),RunWithContext(...)илиRunWebhookWithContext(...) - Закрыть bot через
Close()
Частые ошибки на старте
Нет токена
NewBot(...) вернет ошибку, если токен не настроен.
Нет плагинов
Запуск бота без зарегистрированных плагинов невалиден.
Неожидание, что ctx.Text уже очищен от команды
Для обычного потока команд:
- сообщение:
/echo hello world - имя команды:
echo ctx.Text:hello worldctx.Args:[]string{"hello", "world"}
Использование value types для shared state
Обычно лучше использовать pointer types, чтобы не копировать общий state по значению.
Куда идти дальше
Navigation
Start here
Runtime and Architecture
- Bot-Lifecycle
- Webhook-Runtime
- Middleware
- Runners
- Error-Handling
- Logging
- Update-Routing-Model
- Policies
- Scenes
Interaction and Telegram API
- Inline-Keyboards-and-Payloads
- Auto-Generated-Commands
- Drafts
- Rich-Messages
- Localization
- Rate-Limiting
- tgapi-Overview