¿Qué hace A Arquitectura Hexagonal?
Analiza en profundidad un repositorio existente y diseña un plan de refactorización atómico y por fases para migrarlo a Arquitectura Hexagonal (Puertos y Adaptadores) sin romper ningún contrato externo ni comportamiento observable.
Responde en el mismo idioma de la solicitud del usuario. Opera estrictamente en Modo Plan: inspecciona el código base primero y entrega el plan completo antes de modificar cualquier archivo.
Cuándo Usarlo
- El usuario solicita migrar o refactorizar un proyecto existente hacia Arquitectura Hexagonal o Puertos y Adaptadores.
- El usuario quiere desacoplar la lógica de negocio de frameworks web, ORMs, bases de datos, brokers de mensajes o SDKs externos.
- El usuario pide un plan de refactorización arquitectónica seguro, incremental y con cero cambios disruptivos.
Principios Fundamentales
- Cero Cambios Disruptivos (Regla de Oro): Preserva cada contrato externo existente. Las rutas, métodos HTTP, códigos de estado, esquemas de payload de solicitud/respuesta, encabezados, formatos de error, banderas de CLI o formas de mensajes de cola deben permanecer idénticos.
- Caracterización Antes de Refactorizar: Nunca muevas o elimines lógica de producción hasta que pruebas automatizadas de contrato/caracterización cubran los endpoints o puntos de entrada existentes.
- Regla de Dependencia Estricta: Las dependencias del código fuente siempre deben apuntar hacia adentro, hacia el
domain. La capa de dominio debe tener cero importaciones de frameworks web, controladores de bases de datos, ORMs, bibliotecas de serialización o SDKs externos. - Adaptación Idiomática del Stack: Adapta las rutas de directorios, convenciones de nomenclatura, construcciones de tipado y ejecutores de pruebas al lenguaje y ecosistema detectados del proyecto (por ejemplo, TypeScript/Node, Python, Go, Java/Kotlin, C#, Rust).
Flujo de Trabajo
Paso 1: Descubrimiento del Código Base
Escanea el repositorio antes de proponer cualquier árbol de carpetas o pasos de migración:
- Stack y Herramientas: Inspecciona los manifiestos de dependencias, configuraciones de compilador/linter y ejecutores de pruebas para identificar el lenguaje, framework, biblioteca de validación, ORM/constructor de consultas y enfoque de DI.
- Puntos de Entrada y Contratos: Inventaria todos los puntos de entrada principales (rutas HTTP, resolutores GraphQL, servicios gRPC, consumidores de mensajes, trabajos cron), sus esquemas de validación, middlewares/interceptores y manejadores de errores globales.
- Dependencias Externas: Inventaria todos los efectos secundarios impulsados (bases de datos, cachés, clientes HTTP/RPC, colas, almacenamiento de archivos, configuración de entorno, registradores).
- Flujo de Ejecución Actual: Traza cómo fluyen los datos actualmente desde el punto de entrada hasta la persistencia/llamada externa y de vuelta, notando dónde se mezclan las reglas de negocio con detalles de transporte o persistencia.
Paso 2: Diseñar la Estructura Hexagonal Objetivo
Mapea las tres capas concéntricas a la raíz de código fuente idiomática del proyecto (por ejemplo, src/ en TypeScript/Rust, internal/ en Go, src/main/<lang>/ en JVM, o el directorio del paquete principal en Python):
domain/(Núcleo de Negocio Puro - cero dependencias de framework o E/S):entities/yvalue-objects/: Modelos de dominio que encapsulan reglas de negocio, invariantes y autovalidación.ports/in/: Interfaces de puertos principales que definen contratos de casos de uso.ports/out/: Interfaces de puertos secundarios que definen contratos de repositorio, servicio externo, publicador de eventos yLoggerPort.errors/: Excepciones semánticas de dominio (por ejemplo,ResourceNotFoundError,DomainValidationError,ConflictError).
application/(Orquestación de Casos de Uso):use-cases/: Implementaciones deports/inque coordinan entidades de dominio yports/out.dtos/: Estructuras de datos de entrada y salida inmutables, desacopladas de los payloads de transporte y las entidades de persistencia.
infrastructure/(Detalles Técnicos y Adaptadores):adapters/in/: Adaptadores principales (controladores/manejadores HTTP, manejadores de consumidores), esquemas de validación de transporte, mapeadores (TransportInput -> InputDTOyOutputDTO -> TransportOutput), y un mapeador de errores global que traducedomain/errorsa las respuestas de error exactas del legado.adapters/out/: Implementaciones concretas deports/out(repositorios de base de datos, clientes HTTP, brokers) con mapeadores de persistencia/externos para que los modelos ORM o tipos SDK nunca se filtren aldomain.config/: Carga estricta y validación de inicio de variables de entorno y configuraciones de ejecución.di/(Raíz de Composición): Cableado explícito de adaptadores secundarios, casos de uso y adaptadores principales mediante inyección de constructor, evitando singletons ocultos o localizadores de servicios.
- Separación del Arranque: Separa la construcción de la aplicación (
buildApp/ función de fábrica para pruebas de integración aisladas) del inicio del servidor/proceso (main/listen).
Paso 3: Aplicar Estándares de Ingeniería en el Plan
Asegura que cada fase del plan aplique:
- Tipado Fuerte e Inmutabilidad: Prohíbe escapes sin tipo (como
anyo mapas sin tipo donde corresponden estructuras tipadas) y favorece DTOs y Value Objects inmutables (readonly, dataclasses congeladas, registros, tipos valor). - SOLID e Inyección de Constructor: Mantén las clases y funciones pequeñas con responsabilidades únicas; inyecta interfaces a través de constructores.
- Observabilidad sin Acoplamiento: Preserva el registro estructurado y el contexto de correlación de solicitudes, manteniendo
domain/yapplication/desacoplados de bibliotecas de registro específicas medianteLoggerPort. - Pruebas Piramidales:
- Pruebas unitarias para
domain/(invariantes puras) yapplication/(simulandoports/out). - Pruebas de integración/contrato que verifiquen los adaptadores principales reales contra el cableado de la aplicación utilizando el cliente de prueba en memoria nativo del stack (por ejemplo,
fastify.inject, Supertest, FastAPITestClient, SpringMockMvco Gohttptest).
- Pruebas unitarias para
Formato de Salida (Modo Plan)
Entrega la respuesta estructurada en estas secciones exactas:
- Diagnóstico de la Arquitectura Actual: Inventario conciso del stack detectado, puntos de entrada/endpoints, dependencias externas y principales puntos calientes de acoplamiento.
- Árbol de Directorios Objetivo: Estructura de carpetas propuesta completa utilizando los nombres de módulos y características reales encontrados en el repositorio.
- Plan de Ejecución por Fases: Cinco fases atómicas y verificables:
- Fase 1 - Pruebas de Caracterización y Andamiaje Base: Crea pruebas de contrato que bloqueen el comportamiento actual, crea las carpetas objetivo, el cargador de configuración y la raíz de composición (
di/). - Fase 2 - Extracción del Dominio: Extrae entidades, value objects, errores de dominio e interfaces de
ports/in+ports/outcon pruebas unitarias. - Fase 3 - Casos de Uso de Aplicación y Adaptadores Secundarios: Implementa casos de uso, DTOs, repositorios/clientes de
adapters/outy mapeadores de persistencia. - Fase 4 - Adaptadores Principales y Traducción de Errores: Refactoriza controladores/manejadores para delegar en casos de uso a través de mapeadores, cablea la traducción de errores global y conecta
di/. - Fase 5 - Limpieza del Legado y Verificación Final: Elimina archivos obsoletos, ejecuta el conjunto completo de pruebas, el linter y el verificador de tipos, y verifica cero desviaciones de contrato.
- Fase 1 - Pruebas de Caracterización y Andamiaje Base: Crea pruebas de contrato que bloqueen el comportamiento actual, crea las carpetas objetivo, el cargador de configuración y la raíz de composición (
- Puntos de Control de Validación: Comando o verificación explícita al final de cada fase que demuestre que nada se rompió antes de avanzar a la siguiente fase.
Trampas Comunes
- No edites código prematuramente: A menos que el usuario solicite explícitamente comenzar a ejecutar la Fase 1 de inmediato, primero entrega solo el plan para que puedan revisar los límites de los módulos.
- Evita la sobre-abstracción en CRUD triviales: Aún así separa claramente
domain,applicationeinfrastructure, pero mantén los casos de uso de paso a través concisos en lugar de inventar complejidad de dominio artificial. - Iguala peculiaridades del legado: Si un endpoint existente devuelve un código de estado no estándar o un nombre de campo de error, documéntalo en la Fase 1 y presérvalo en el mapeador de errores de
infrastructurepara que los clientes existentes no se rompan.