Estructura libre o fija: cómo elegir

Ambos modelos producen errores estructurados. Por eso usamos composición libre para la alternativa a una familia tipada: también puede formar árboles, tener metadatos y usar clases propias.

Qué necesitas para cada modelo

Aspecto	Composición libre	Familia tipada
Base	Error y Reason	Raíz y razones con relaciones declaradas
Referencia	Greencore.Platform.Errors	Platform.Errors y el módulo de cada familia; Platform.Processes para procesos
Preparación	Crear nodos y acordar su significado	Usar una familia predefinida o definir sus tipos
Relación padre-hijo	Composición flexible	Compatibilidad comprobada por el compilador
Datos	Mensajes, metadatos o clases propias	Propiedades específicas, además de mensajes y metadatos
Sintaxis	AddReason, WithReason	Operaciones generales y métodos específicos
Consumo	Convenciones compartidas por la aplicación	Tipos, propiedades y códigos de la familia

El mismo diagnóstico con composición libre

using Greencore.Platform.Errors;

var error = Error.Create("El libro contiene datos inválidos");
var row = error.AddReason("Fila 12").WithMetadata("Row", 12);
var cell = row.AddReason("Celda B12").WithMetadata("Address", "B12");
cell.AddReason("El valor es obligatorio").WithMetadata("Code", "validation.required");

La aplicación decide qué claves usar y qué significa cada nivel. También puede derivar de Reason para conservar datos propios; la composición libre no obliga a almacenar todo como texto.

Con una familia propia

Con las clases completas de Excel:

var error = new ExcelImportError("clientes.xlsx");
error.AddSheet("Clientes")
    .AddRow(12)
    .AddCell("B12")
    .Required();

AddRow, AddCell y Required son métodos de esa familia del ejemplo. Hacen explícita la intención y evitan repetir constructores y códigos.

Una celda declara una fila como padre. Intentar agregarla directamente a la raíz no compila. Al consumir el diagnóstico, ExcelCellReason.Address y sus padres permiten recuperar la ubicación sin convertir metadatos.

Los árboles de diagnóstico personalizados bien diseñados pueden hacer más legible la composición de árboles de errores. Sus métodos específicos expresan el vocabulario de la operación y ocultan la construcción repetitiva de razones. Para lograrlo, usa nombres claros y retornos consistentes; una cadena demasiado anidada puede ser menos clara que varias variables intermedias. La composición fluida de DomainError muestra esta idea con la familia predefinida.

Cuándo elegir cada uno

Usa composición libre para diagnósticos puntuales, estructuras variables o exploración inicial. Permite comenzar con pocos tipos y acordar convenciones conforme aparecen necesidades.

Usa una familia predefinida cuando el problema ya encaja en entidades y propiedades o en causas de ejecución. Obtienes sintaxis y clasificaciones consistentes sin diseñar la jerarquía.

Crea una familia propia cuando varios productores y consumidores comparten una estructura estable: importaciones, exportaciones o procesamiento por lotes. El trabajo inicial de definir tipos reduce convenciones repetidas y simplifica informes y consultas.

Límites del tipado

El tipado comprueba compatibilidad de padres, no que el dato esté validado ni que una dirección Excel exista. Tampoco impone una lista cerrada de hijos: se pueden añadir tipos que declaren el mismo padre. Las APIs admiten razones textuales tipadas.

Ambos modelos tienen recorrido y formato comunes mediante INode y las herramientas de árboles. Véase recorrer errores.