Boas práticas para erros

Criando uma exceção personalizada

Quando as exceções embutidas não cobrem o seu cenário de domínio, você cria uma classe personalizada estendendo SpraxiumException. Uma exceção personalizada define seu próprio code, uma message com placeholders e uma interface tipada de props que carrega o contexto de runtime tanto para logging quanto para renderização de layout. Isso entrega ao pipeline tudo de que ele precisa para produzir uma resposta útil para a pessoa usuária e um sinal operacional sem nenhuma integração adicional.

import { SpraxiumException } from '@spraxium/core';

interface InsufficientBalanceProps {
  required: number;
  current: number;
  currency: string;
}

export class InsufficientBalanceException extends SpraxiumException {
  constructor(props: InsufficientBalanceProps) {
    super({
      code: 'INSUFFICIENT_BALANCE',
      message: 'You need {{required}} {{currency}} but only have {{current}}.',
      props,
    });
  }
}

A interface tipada de props é importante porque dá aos layouts e ao logging acesso a dados estruturados em vez de uma string opaca. Qualquer chave do objeto props pode ser interpolada em message usando a sintaxe com chaves duplas, e os layouts recebem o objeto props inteiro para poder montar embeds ricos, formatar números ou exibir orientações contextuais para a pessoa usuária.

Lançando a exceção personalizada

Use a exceção personalizada dentro de services, guards ou handlers exatamente como qualquer exceção embutida. O pipeline resolve o layout, registra logs se estiver configurado e envia a resposta automaticamente, sem código extra no ponto em que a exceção é lançada.

import { InsufficientBalanceException } from './exceptions/insufficient-balance.exception';

if (user.balance < item.price) {
  throw new InsufficientBalanceException({
    required: item.price,
    current: user.balance,
    currency: 'coins',
  });
}

Associando um layout com @WithLayout

Se a exceção precisar vir com uma apresentação visual padrão, associe um layout usando o decorator @WithLayout de @spraxium/common. O layout recebe a instância da exceção com acesso completo a props e ao contexto de execução, e retorna um payload de resposta do Discord com embeds, componentes e flags efêmeras.

import { WithLayout } from '@spraxium/common';
import { defineExceptionLayout, SpraxiumException } from '@spraxium/core';
import { EmbedBuilder } from 'discord.js';

const BalanceLayout = defineExceptionLayout((exception) => ({
  embeds: [
    new EmbedBuilder()
      .setColor(0xff6b6b)
      .setTitle('Insufficient Balance')
      .setDescription(
        `You need **${exception.props.required} ${exception.props.currency}** but only have **${exception.props.current}**.`,
      )
      .setFooter({ text: 'Earn more by completing daily tasks.' }),
  ],
  ephemeral: true,
}));

@WithLayout(BalanceLayout)
export class InsufficientBalanceException extends SpraxiumException {
  constructor(props: { required: number; current: number; currency: string }) {
    super({
      code: 'INSUFFICIENT_BALANCE',
      message: 'You need {{required}} {{currency}} but only have {{current}}.',
      props,
    });
  }
}

Controlando o comportamento de resposta e logging

Cada exceção personalizada pode sobrescrever se o pipeline deve enviar uma resposta no Discord e se deve registrar o erro em log. A flag shouldReply tem valor padrão true, o que faz sentido para falhas voltadas ao usuário, e shouldLog tem valor padrão false porque a maior parte das exceções de domínio representa comportamento esperado, não incidentes. Sobrescreva esses padrões quando a exceção representar uma operação silenciosa ou um erro interno que precisa aparecer nos logs operacionais.

export class SilentAuditException extends SpraxiumException {
  constructor(props: { action: string; actorId: string }) {
    super({
      code: 'SILENT_AUDIT',
      message: 'Audit recorded for {{action}} by {{actorId}}.',
      props,
      shouldReply: false,
      shouldLog: true,
    });
  }
}

Princípio central

A qualidade das exceções começa pela clareza de intenção, ou seja, toda exceção deve responder a três perguntas de arquitetura: o que falhou, por que falhou e qual ação deve acontecer em seguida para usuários ou operadores. Quando classes de exceção não comunicam essas dimensões com clareza, o custo aparece rápido na forma de experiências vagas para o usuário, logs barulhentos e difíceis de filtrar e uma triagem de incidentes mais lenta, porque a equipe não consegue entender, só pelo erro, o que realmente aconteceu.

Padrões recomendados

Antipadrões a evitar

Lançar exceções genéricas para todo cenário pode parecer mais rápido no começo, mas isso prejudica a manutenibilidade e a observabilidade com o tempo, porque todo erro passa a parecer igual nos logs e não existe uma forma clara de direcionar tipos específicos de falha para layouts dedicados ou regras de monitoramento. Outro erro frequente é esconder contexto importante dentro de strings livres, que não podem ser consultadas, agregadas ou filtradas em ferramentas de análise de logs. Um terceiro antipadrão é acoplar a lógica de UI do erro diretamente dentro de services de domínio, tornando o service responsável tanto por decisões de negócio quanto pela renderização da resposta, quando essas responsabilidades deveriam estar claramente separadas.

Fluxo operacional recomendado