maxrouter

README

Max Router

Гибкий и мощный роутер для Max Bot API Client@v1.6.15, вдохновленный принципами go-chi.

Роутер предоставляет удобный интерфейс для обработки сообщений, команд и callback-запросов, поддерживая middleware и группировку маршрутов.

Установка

go get github.com/LZTD1/max-router@v1.2.0

Возможности (Features)

Max Router делает разработку бота простой, чистой и эффективной:

1. Интеллектуальная маршрутизация: Роутер автоматически определяет, как обработать сообщение, стараясь сделать это за меньшее время.
2. Гибкие Middleware: Вы можете легко создавать цепочки обработки для всей системы или отдельных групп маршрутов.
3. MaxContext: Вместо работы с «сырыми» данными SDK, ваш хендлер получает готовый инструмент для работы с пользователем - Context.
4. Асинхронность из коробки: Роутер поддерживает параллельную обработку сообщений.

Простой пример использования

func main() {
    ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, os.Interrupt)
    defer stop()
    
    api, _ := maxbot.New(
        os.Getenv("MAX_TOKEN"),
    )
    
    // Инициализация роутера
    r := maxrouter.NewRouter(api)
    r.Use(middleware.Recover()) // Защита от паники
    r.Use(middleware.DefaultLogger())
    
    // --- Регистрация хендлера на команду /start ---
    r.HandleCommand("/start", func(ctx maxrouter.Context) error {
        return ctx.Send("Привет!")
    })
    r.HandleText("Кто ты?", func(ctx maxrouter.Context) error {
        return ctx.Reply("Я бот!")
    })
	
    // --- Обработка неизвестных команд (NotFound) ---
    r.NotFound(func(c maxrouter.Context) error {
        return c.Send("Извините, такую команду я еще не умею обрабатывать")
    })
    
    // --- Start polling ---
    for update := range api.GetUpdates(ctx) {
        r.Handle(update, ctx)
    }
}

Для корректной работы роутера рекомендуется использование встроенных в контекст методов Send, Reply и т.д. Использование std API внутри роутера может привести к некорректной работе.

Примеры

Все примеры предоставлены в директории _examples:

• Обработка сообщений и нажатий на кнопки
• Работа с регулярными выражениями
• Использование Middleware: Применение глобальных и Scoped Middleware

История версий

• v1.2.0: Добавлены методы для работы с пользователем User(), Username(), FullName() и т.д.
• v1.1.1: Добавлены примеры и миграция на новую версию maxbot, расширены тесты middleware
• v1.1.0: Интеграция передачи контекста в обработчики запросов
• v1.0.1: Оптимизация контекста (удален mutex)
• v1.0.0: Релиз

License

Licensed under MIT License

Documentation

Index

• Variables
• type Context
• type ErrorHandler
• type HandlerFunc
  • func (f HandlerFunc) ServeContext(ctx Context) error
• type Middleware
• type Option
  • func WithAttachments(a ...any) Option
  • func WithFormat(format schemes.Format) Option
  • func WithKeyboard(kb *maxbot.Keyboard) Option
  • func WithNotify(notify bool) Option
  • func WithReplyTo(messageID string) Option
• type RouteHandler
• type Router
  • func NewRouter(api *maxbot.Api, opts ...RouterOption) *Router
  • func (r *Router) Group(fn func(sub *Router))
  • func (r *Router) Handle(upd schemes.UpdateInterface, ctx context.Context)
  • func (r *Router) HandleCallback(payload string, f HandlerFunc)
  • func (r *Router) HandleCommand(cmd string, f HandlerFunc)
  • func (r *Router) HandleCtx(ctx context.Context, upd schemes.UpdateInterface) error
  • func (r *Router) HandleRegexpCallback(re *regexp.Regexp, f HandlerFunc)
  • func (r *Router) HandleRegexpText(re *regexp.Regexp, f HandlerFunc)
  • func (r *Router) HandleStart(f HandlerFunc)
  • func (r *Router) HandleText(text string, f HandlerFunc)
  • func (r *Router) HandleType(t schemes.UpdateType, f HandlerFunc)
  • func (r *Router) NotFound(f HandlerFunc)
  • func (r *Router) OnError(eh ErrorHandler)
  • func (r *Router) Use(mws ...Middleware)
  • func (r *Router) With(mws ...Middleware) *Router
• type RouterOption
  • func WithAsync(async bool) RouterOption
• type SendOptions

Variables

var (
	ErrNilHandler  = errors.New("maxrouter: handler is nil")
	ErrEmptyString = errors.New("maxrouter: pattern string is empty")
	ErrNilAPI      = errors.New("maxrouter: api is nil")
)

Types

type Context

type Context interface {
	Update() schemes.UpdateInterface
	API() *maxbot.Api
	Ctx() context.Context

	Message() *schemes.Message
	Callback() *schemes.Callback
	Text() string
	Command() string
	Data() string
	ChatID() int64
	UserID() int64

	Set(key string, val any)
	Get(key string) (any, bool)

	Send(text string, opts ...Option) error
	Reply(text string, opts ...Option) error
	Edit(text string, opts ...Option) error
	Answer(notification string) error

	User() *schemes.User
	FullName() string
	Username() string
	FirstName() string
	LastName() string

	Handled() bool
}

type ErrorHandler

type ErrorHandler func(err error, ctx Context)

type HandlerFunc

type HandlerFunc func(ctx Context) error

func (HandlerFunc) ServeContext

func (f HandlerFunc) ServeContext(ctx Context) error

type Middleware

type Middleware func(next RouteHandler) RouteHandler

type Option

type Option func(*SendOptions)

func WithAttachments

func WithAttachments(a ...any) Option

func WithFormat

func WithFormat(format schemes.Format) Option

func WithKeyboard

func WithKeyboard(kb *maxbot.Keyboard) Option

func WithNotify

func WithNotify(notify bool) Option

func WithReplyTo

func WithReplyTo(messageID string) Option

type RouteHandler

type RouteHandler interface {
	ServeContext(ctx Context) error
}

type Router

type Router struct {
	// contains filtered or unexported fields
}

func NewRouter

func NewRouter(api *maxbot.Api, opts ...RouterOption) *Router

func (*Router) Group

func (r *Router) Group(fn func(sub *Router))

func (*Router) Handle

func (r *Router) Handle(upd schemes.UpdateInterface, ctx context.Context)

func (*Router) HandleCallback

func (r *Router) HandleCallback(payload string, f HandlerFunc)

func (*Router) HandleCommand

func (r *Router) HandleCommand(cmd string, f HandlerFunc)

func (*Router) HandleCtx

func (r *Router) HandleCtx(ctx context.Context, upd schemes.UpdateInterface) error

func (*Router) HandleRegexpCallback

func (r *Router) HandleRegexpCallback(re *regexp.Regexp, f HandlerFunc)

func (*Router) HandleRegexpText

func (r *Router) HandleRegexpText(re *regexp.Regexp, f HandlerFunc)

func (*Router) HandleStart

func (r *Router) HandleStart(f HandlerFunc)

func (*Router) HandleText

func (r *Router) HandleText(text string, f HandlerFunc)

func (*Router) HandleType

func (r *Router) HandleType(t schemes.UpdateType, f HandlerFunc)

func (*Router) NotFound

func (r *Router) NotFound(f HandlerFunc)

func (*Router) OnError

func (r *Router) OnError(eh ErrorHandler)

func (*Router) Use

func (r *Router) Use(mws ...Middleware)

func (*Router) With

func (r *Router) With(mws ...Middleware) *Router

type RouterOption

type RouterOption func(*Router)

func WithAsync

func WithAsync(async bool) RouterOption

type SendOptions

type SendOptions struct {
	Keyboard    *maxbot.Keyboard
	Attachments []any
	ReplyToID   string
	Notify      bool
	Format      schemes.Format
}