O modelo de interações
Entenda como interações do Discord percorrem discordgo, Router, middleware, Context e handlers no DiscordKit.
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.
O fluxo completo
Seção intitulada “O fluxo completo”Em alto nível:
Discord │ │ Interação ▼discordgo.Session │ ▼Router.Handle │ ▼Context │ ▼Resolução da rota │ ▼Middleware global │ ▼Middleware da rota │ ▼Handler │ ▼Resposta │ ▼DiscordEntender cada etapa facilita bastante o restante do framework.
O Discord envia uma interação
Seção intitulada “O Discord envia uma interação”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.
Router.Handle é um handler do discordgo
Seção intitulada “Router.Handle é um handler do discordgo”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.
Context representa uma única interação
Seção intitulada “Context representa uma única interação”Todo handler recebe:
*discordkit.ContextUm 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.Contextpadrã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.
Comandos
Seção intitulada “Comandos”router.Command("ping", pingHandler)Subcomandos usam o caminho completo:
router.Command("admin ban", banHandler)Componentes
Seção intitulada “Componentes”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,)Autocomplete
Seção intitulada “Autocomplete”Rotas de autocomplete combinam o caminho do comando com o nome da opção em foco:
router.Autocomplete( "search", "query", searchAutocomplete,)Middleware envolve handlers
Seção intitulada “Middleware envolve handlers”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) HandlerExemplo:
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, ),)Recovery sempre é aplicado
Seção intitulada “Recovery sempre é aplicado”O Router aplica automaticamente o mecanismo de recovery do DiscordKit ao redor da execução.
Se um handler causar panic, ele é convertido em:
*discordkit.PanicErrorem 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.
Handlers retornam erros
Seção intitulada “Handlers retornam erros”Um Handler possui a forma:
type Handler func(*Context) errorEsse 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.
Respostas reconhecem a interação
Seção intitulada “Respostas reconhecem a interação”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 errDiscordKit acompanha esse estado e impede sequências inválidas, como tentar enviar duas respostas iniciais para a mesma interação.
Um Router, vários tipos de interação
Seção intitulada “Um Router, vários tipos de 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.
Modelo mental
Seção intitulada “Modelo mental”Uma forma útil de pensar no DiscordKit é:
Interação do Discord +informação de roteamento +middleware da aplicação =execução do handlerO framework não tenta esconder o Discord.
Ele fornece um caminho estruturado entre a interação recebida e o código da aplicação.
Próximo passo
Seção intitulada “Próximo passo”Continue em Router para entender registro de rotas, parâmetros, grupos, conflitos e composição de middleware.