Padrões de Arquitetura de Listeners

Listeners como fronteiras de evento

Um listener deve ser a fronteira mais fina possível entre um evento do Discord e a sua lógica de domínio. A função dele é receber o payload do evento, fazer filtros básicos, como ignorar contas de bot, e então chamar o serviço responsável pela regra de negócio. Quando o listener fica fino, o código de domínio continua testável sem precisar simular o sistema de eventos do Discord, e o próprio listener segue legível porque faz muito pouco por conta própria.

O caminho oposto, que é jogar a lógica de negócio diretamente dentro dos métodos do listener, até funciona em bots pequenos, mas degrada rápido quando a base cresce. Se o algoritmo de ranking da sua leaderboard vive dentro de MessageCreateListener, você não consegue testá-lo sem simular mensagens do Discord. Se amanhã a mesma lógica precisar rodar em uma rota de API ou em um job agendado, você vai ter de extrair isso de qualquer forma. Começar com delegação para serviço evita esse retrabalho desde o início.

Esse padrão também deixa bem claro onde investigar quando algo quebra. Se o evento não dispara de jeito nenhum, o problema está no binding do listener ou nos gateway intents. Se o evento dispara, mas o resultado é errado, o problema tende a estar no serviço. Como cada camada tem uma responsabilidade estreita e objetiva, o debug fica mais rápido.

Exemplo de delegação para serviço

Aqui está o padrão em prática. O listener recebe MessageCreate, verifica se o autor é um bot e depois delega para um LeaderboardService, que cuida da lógica real de tracking. O listener não sabe como a pontuação funciona, e o serviço não precisa saber que foi chamado a partir de um evento do Discord.

import { Events, Listener, On } from '@spraxium/common';
import { Logger } from '@spraxium/core';
import type { Message } from 'discord.js';
import { LeaderboardService } from '../../services/leaderboard.service';

@Listener(Events.MessageCreate)
export class MessageCreateListener {
  private readonly logger = new Logger(MessageCreateListener.name);

  constructor(private readonly leaderboard: LeaderboardService) {}

  @On()
  async onMessage(message: Message): Promise<void> {
    if (message.author.bot) return;
    this.logger.debug(`Message from ${message.author.id} in guild ${message.guildId}`);
    await this.leaderboard.trackMessage(message.author.id, message.guildId);
  }
}

O serviço é uma classe injetável comum, registrada pelo módulo no array providers. O listener a recebe por injeção de construtor e chama seus métodos. Se amanhã a mesma regra de pontuação precisar ser usada em outro ponto de entrada, basta injetar o mesmo serviço ali, sem duplicar lógica.

Organização do módulo

Um módulo de eventos bem organizado agrupa listeners relacionados e mantém o arquivo de declaração do módulo na raiz da pasta. Conforme o bot passa a lidar com mais eventos, essa estrutura continua escalando sem virar um labirinto. Cada arquivo de listener cuida de um evento, e o arquivo do módulo funciona como índice do que está realmente ativo.

O módulo amarra tudo listando listeners e providers em um único lugar. Quem abre esse arquivo entende imediatamente quais eventos aquela área trata e quais serviços estão disponíveis para injeção.

import { Module } from '@spraxium/common';
import { LeaderboardService } from '../services/leaderboard.service';
import { WelcomeService } from '../services/welcome.service';
import { MemberJoinListener } from './listeners/member-join.listener';
import { MemberLeaveListener } from './listeners/member-leave.listener';
import { MessageCreateListener } from './listeners/message-create.listener';
import { ReadyListener } from './listeners/ready.listener';

@Module({
  providers: [LeaderboardService, WelcomeService],
  listeners: [
    ReadyListener,
    MessageCreateListener,
    MemberJoinListener,
    MemberLeaveListener,
  ],
})
export class EventsModule {}

Padrões práticos para métodos de listener

Métodos de listener devem seguir uma estrutura consistente para continuar previsíveis em toda a codebase. Comece com retornos antecipados para eventos irrelevantes, faça qualquer transformação leve necessária e só depois chame o serviço. Esse padrão em três passos deixa cada método fácil de revisar e difícil de complicar sem necessidade.