Pular para o conteúdo
Documentação DiscordKit

O modelo de interações

Entenda como interações do Discord percorrem discordgo, Router, middleware, Context e handlers no DiscordKit.

Abrir texto

Grande parte do DiscordKit é construída em torno de uma ideia:

o Discord envia interações, e sua aplicação as encaminha para handlers.

Comandos são apenas um dos tipos de interação.

DiscordKit utiliza o mesmo modelo de aplicação para comandos, componentes, submissões de modais e autocomplete.

Em alto nível:

Discord
│
│ Interação
▼
discordgo.Session
│
▼
Router.Handle
│
▼
Context
│
▼
Resolução da rota
│
▼
Middleware global
│
▼
Middleware da rota
│
▼
Handler
│
▼
Resposta
│
▼
Discord

Entender cada etapa facilita bastante o restante do framework.

Interações podem ser geradas por ações como:

  • executar um slash command;
  • usar um comando de contexto de usuário;
  • usar um comando de contexto de mensagem;
  • clicar em um botão;
  • selecionar uma opção em um select;
  • enviar um modal;
  • digitar em uma opção com autocomplete.

discordgo recebe essas interações diretamente do Discord.

DiscordKit não substitui essa conexão.

Um Router do DiscordKit é conectado ao discordgo assim:

session.AddHandler(router.Handle)

Router.Handle adapta a interação recebida para o modelo de aplicação do DiscordKit.

Ele cria um Context e encaminha a interação pelo Router.

Todo handler recebe:

*discordkit.Context

Um Context existe para exatamente uma interação.

Ele oferece acesso a:

  • *discordgo.Session;
  • interação original;
  • opções de comandos;
  • usuários, roles, canais, membros e anexos resolvidos;
  • parâmetros de rota;
  • dados de formulários;
  • helpers de resposta;
  • context.Context padrão do Go.

Exemplo:

func greet(c *discordkit.Context) error {
user, err := c.RequireUserOption("user")
if err != nil {
return err
}
return c.ReplyText("Hello, " + user.Username)
}

A resolução da rota depende do tipo da interação

Seção intitulada “A resolução da rota depende do tipo da interação”

DiscordKit possui quatro categorias principais de rota.

router.Command("ping", pingHandler)

Subcomandos usam o caminho completo:

router.Command("admin ban", banHandler)

Componentes são roteados através do custom_id:

router.Component(
"/jobs/:jobID/save",
saveJobHandler,
)

Parâmetros nomeados ficam disponíveis no Context:

jobID := c.MustParam("jobID")

Submissões de modais usam o mesmo modelo de rotas parametrizadas:

router.Modal(
"/jobs/:jobID/edit",
editJobHandler,
)

Rotas de autocomplete combinam o caminho do comando com o nome da opção em foco:

router.Autocomplete(
"search",
"query",
searchAutocomplete,
)

Middleware permite executar lógica antes ou depois dos handlers.

DiscordKit utiliza o padrão tradicional de composição do Go:

type Middleware func(Handler) Handler

Exemplo:

router := discordkit.NewRouter(
discordkit.Logging(nil),
discordkit.RequireGuild(),
)

Middleware global é aplicado às rotas correspondentes.

Também é possível adicionar middleware apenas a uma rota:

router.Command(
"admin",
adminHandler,
discordkit.RequirePermissions(
discordgo.PermissionAdministrator,
),
)

O Router aplica automaticamente o mecanismo de recovery do DiscordKit ao redor da execução.

Se um handler causar panic, ele é convertido em:

*discordkit.PanicError

em vez de escapar diretamente do handler de interação.

Recovery não envia automaticamente uma mensagem de erro ao usuário.

A aplicação continua responsável por decidir como erros devem ser apresentados.

Um Handler possui a forma:

type Handler func(*Context) error

Esse modelo permite que erros atravessem middleware e cheguem até o tratamento central do Router.

Por exemplo:

router.OnError(func(c *discordkit.Context, err error) {
slog.Error("interaction failed", "error", err)
})

Sem um hook personalizado, DiscordKit registra o erro usando slog.

Interações precisam ser reconhecidas conforme as regras da API do Discord.

Um handler pode responder imediatamente:

return c.ReplyText("Done")

ou adiar a resposta:

if err := c.Defer(false); err != nil {
return err
}
// trabalho...
_, err := c.Edit(
discordkit.MessageSpec{
Content: "Done",
},
)
return err

DiscordKit acompanha esse estado e impede sequências inválidas, como tentar enviar duas respostas iniciais para a mesma interação.

Uma aplicação maior pode registrar diferentes tipos de interação no mesmo Router:

router := discordkit.NewRouter(
discordkit.Logging(nil),
)
router.Command(
"jobs search",
searchJobs,
)
router.Component(
"/jobs/:jobID/save",
saveJob,
)
router.Modal(
"/jobs/:jobID/edit",
editJob,
)
router.Autocomplete(
"jobs search",
"query",
autocompleteJobs,
)

Todas essas rotas utilizam o mesmo modelo de Context, Handler, middleware, erros e respostas.

Essa consistência é um dos objetivos centrais do DiscordKit.

Uma forma útil de pensar no DiscordKit é:

Interação do Discord
+
informação de roteamento
+
middleware da aplicação
=
execução do handler

O framework não tenta esconder o Discord.

Ele fornece um caminho estruturado entre a interação recebida e o código da aplicação.

Continue em Router para entender registro de rotas, parâmetros, grupos, conflitos e composição de middleware.