Configuración y Fallback

Por qué configurar excepciones en core

La configuración central de excepciones evita que los equipos manejen la misma categoría de fallo de formas distintas entre módulos. Al definir la política en spraxium.config.ts, el comportamiento en runtime se mantiene coherente incluso cuando múltiples funcionalidades y equipos evolucionan en paralelo, porque cada excepción sigue las mismas reglas de resolución sin importar dónde se origine. Esto también reduce de forma significativa el riesgo en refactors, ya que cambiar la estrategia de fallback o actualizar un mapeo de layout requiere tocar una única ubicación de política en lugar de buscar entre decenas de archivos de comandos y listeners repartidos por el proyecto.

Esta página trata de política, no de implementación. El objetivo es decidir cómo debe responder la aplicación cuando una excepción escapa de un handler, qué layout debe renderizarla y cuánto debe registrarse para operadores.

Configuración mínima

Una base pequeña ya da control significativo sobre cómo tu bot maneja errores en producción. Definir un fallback de layout por defecto y una política de logging para no manejadas garantiza que toda excepción del sistema produzca una respuesta para el usuario y una señal operativa, incluso cuando todavía no has mapeado esa clase de excepción a un layout dedicado. Esto evita respuestas vacías o rotas que confunden a los usuarios durante escenarios de fallo inesperados.

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

export default defineConfig({
  exceptions: {
    logUnhandled: true,
    layouts: {
      default: DefaultFriendlyLayout,
    },
  },
});

Dónde encajan los layouts

Los layouts pertenecen a la política de presentación de errores, y esta página se enfoca en configuración central, comportamiento de fallback y gobernanza mediante mapas de configuración, en lugar de detalles de implementación de layouts. Para la estrategia completa de layouts que cubre qué son los layouts, cómo crearlos, la precedencia entre decoradores y mapeos de configuración, y cuándo usar overrides por instancia, consulta Estrategia de layouts.

Configuración con mapeo por clase

Cuando tu aplicación tiene múltiples dominios como moderación, facturación y onboarding, mapear layouts por clase de excepción preserva el contexto y el tono para cada tipo de fallo. Cada familia de fallos puede devolver lenguaje y guía apropiados para la acción del usuario, lo que mejora de forma significativa la experiencia de error frente a un único mensaje genérico para todos los escenarios del bot.

import { defineConfig } from '@spraxium/core';
import {
  DefaultFriendlyLayout,
  CooldownLayout,
  PermissionDeniedLayout,
  ArgumentLayout,
} from './layouts/exceptions.layouts';

export default defineConfig({
  exceptions: {
    logUnhandled: true,
    layouts: {
      default: DefaultFriendlyLayout,
      CooldownException: CooldownLayout,
      PermissionDeniedException: PermissionDeniedLayout,
      ArgumentException: ArgumentLayout,
    },
  },
});

Referencia de claves de configuración

Cuándo mapear un layout dedicado

Agrega un mapeo de layout dedicado cuando una categoría de fallo necesita su propio tono, guía o estructura. Denegaciones de permisos, cooldowns, argumentos inválidos y excepciones de reglas de negocio son ejemplos comunes, porque la respuesta debería decirle al usuario qué ocurrió y qué hacer después.

No crees un layout personalizado para cada clase de excepción por defecto. Un buen layout por defecto, más un número pequeño de mapeos deliberados, suele ser más fácil de mantener que un mapa enorme de respuestas mínimamente diferentes.

Orden de resolución de layouts

La selección de layout sigue un orden estable que determina cuál renderiza la respuesta cuando coexisten múltiples opciones de personalización. Entender este orden evita ambigüedad cuando overrides locales y configuraciones globales de fallback están activos al mismo tiempo, y te permite apilar políticas de forma predecible de lo más específico a lo más general.

1. Override por instancia a través del objeto de excepción directamente
2. Entrada en el mapa de layouts de config que coincide con el nombre de la clase de excepción
3. Layout a nivel de decorador de clase definido con @WithLayout()
4. Layout por defecto definido en la configuración
5. Layout por defecto integrado del framework como fallback final

Estrategia por entorno

Una base común de equipo es mantener activada la opción de logging de no manejadas en staging y producción, mientras se conservan layouts amigables en todos los entornos. Esto mantiene diagnósticos sólidos para operaciones sin filtrar detalles internos al usuario, porque el layout comunica con usuarios mientras el logging comunica con el equipo responsable de monitoreo y respuesta a incidentes.

Una división de política práctica se ve así:

1. Desarrollo local: layouts amigables, logging de no manejadas activado, iteración rápida.
2. Staging: layouts amigables, logging de no manejadas activado, paridad con el comportamiento de producción.
3. Producción: layouts amigables, logging de no manejadas activado, mapeos por clase solo para familias de fallos importantes de cara al usuario.