Buenas Prácticas de Errores

Crear una excepción personalizada

Cuando las excepciones integradas no cubren tu escenario de dominio, creas una clase personalizada extendiendo SpraxiumException. Una excepción personalizada define su propio code, un message con placeholders y una interfaz props tipada que transporta contexto de runtime tanto para logging como para renderizado de layout. Esto le da al pipeline todo lo que necesita para producir una respuesta significativa para el usuario y una señal operativa sin cableado 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,
    });
  }
}

La interfaz props tipada es importante porque da a los layouts y al logging acceso a datos estructurados en lugar de un string opaco. Cualquier clave dentro del objeto props puede interpolarse en el message usando sintaxis de doble llave, y los layouts reciben el objeto props completo para construir embeds enriquecidos, formatear números o mostrar guía contextual al usuario.

Lanzar la excepción personalizada

Usa la excepción personalizada dentro de services, guards o handlers exactamente igual que cualquier excepción integrada. El pipeline resuelve el layout, registra si está configurado y envía la respuesta automáticamente sin código extra en el punto de lanzamiento.

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

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

Adjuntar un layout con @WithLayout

Si la excepción debe distribuirse con una presentación visual por defecto, adjunta un layout usando el decorador @WithLayout de @spraxium/common. El layout recibe la instancia de excepción con acceso completo a props y el contexto de ejecución, y devuelve un payload de respuesta de Discord con embeds, componentes y flags efímeros.

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,
    });
  }
}

Controlar comportamiento de respuesta y logging

Cada excepción personalizada puede overridear si el pipeline envía una respuesta en Discord y si registra el error. La bandera shouldReply por defecto es true, lo cual es correcto para fallos de cara al usuario, y shouldLog por defecto es false porque la mayoría de excepciones de dominio representan comportamiento esperado más que incidentes. Overridea estos defaults cuando la excepción represente una operación silenciosa o un error interno que deba aparecer en logs operativos.

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,
    });
  }
}

Principio central

La calidad de excepciones comienza con claridad de intención, lo que significa que toda excepción debe responder tres preguntas a nivel arquitectura: qué falló, por qué falló y qué acción debe ocurrir después para usuarios u operadores. Cuando las clases de excepción no comunican claramente esas dimensiones, los costos aparecen rápido en forma de experiencias de usuario vagas, logs ruidosos difíciles de filtrar y triage de incidentes más lento porque el equipo no puede saber solo con el error qué salió mal realmente.

Patrones recomendados

Anti-patrones a evitar

Lanzar excepciones genéricas para todos los escenarios puede parecer más rápido al principio, pero perjudica la mantenibilidad y la observabilidad con el tiempo porque todos los errores se ven iguales en logs y no hay forma de apuntar tipos de fallo específicos con layouts dedicados o reglas de monitoreo. Otro error frecuente es esconder contexto clave dentro de strings libres que no pueden consultarse, agregarse ni filtrarse en herramientas de análisis de logs. Un tercer anti-patrón es acoplar directamente la lógica de UI de error dentro de services de dominio, lo que hace que el service sea responsable tanto de decisiones de negocio como del renderizado de respuestas cuando esas responsabilidades deberían estar claramente separadas.

Flujo operativo recomendado