Arquitectura Hexagonal: Guía Completa con TypeScript

Índice

Parte 1: Fundamentos Teóricos

1. Conceptos Fundamentales y Orígenes

   • Historia y origen (Alistair Cockburn, 2005)
   • El problema que resuelve
   • Componentes principales: Dominio, Puertos y Adaptadores
   • Modelo mental y analogías
   • Referencias originales

2. Principios de Diseño

   • Inversión de dependencias
   • Separación de responsabilidades
   • Independencia de frameworks
   • Testabilidad
   • Ejemplos prácticos

3. Dominio y Entidades

   • Modelado del dominio
   • Entidades vs Value Objects
   • Agregados y raíces de agregado
   • Invariantes de negocio

Parte 2: Puertos y Adaptadores

4. Puertos Primarios (Driving)

   • Definición e interfaces
   • Casos de uso
   • Servicios de aplicación
   • Ejemplo: API de gestión de usuarios

5. Puertos Secundarios (Driven)

   • Repositorios y persistencia
   • Servicios externos
   • Implementaciones concretas
   • Ejemplo: Adaptador de base de datos

6. Comunicación entre Capas

   • DTOs y mapeo
   • Manejo de errores
   • Validación en cada capa
   • Ejemplo: Flujo completo de una petición

Parte 3: Implementación Práctica

7. Organización del Código

   • Estructura de directorios
   • Módulos y paquetes
   • Convenciones de nombres
   • Ejemplo: Proyecto real

8. Testing en Arquitectura Hexagonal

   • Pruebas de dominio
   • Pruebas de casos de uso
   • Pruebas de adaptadores
   • Mocks y stubs

9. Refactoring hacia Hexagonal

   • Identificar código legacy
   • Estrategias de migración
   • Pasos incrementales
   • Ejemplo: Refactor paso a paso

Parte 4: Casos de Estudio

10. Sistema de E-commerce

    • Análisis de requisitos
    • Diseño de arquitectura
    • Implementación completa
    • Lecciones aprendidas

11. Sistema de Gestión de Tareas

    • Modelado del dominio
    • Casos de uso principales
    • Implementación con TypeScript
    • Despliegue y operación

Estructura de Cada Capítulo

1. Introducción Conceptual

   • Explicación clara y didáctica
   • Analogías y diagramas
   • Relación con arquitectura hexagonal

2. Implementación Práctica

   • Código TypeScript paso a paso
   • Explicación de cada componente
   • Buenas prácticas

3. Ejemplo Completo

   • Caso de uso real
   • Implementación completa
   • Análisis del código

4. Conclusión

   • Resumen de conceptos clave
   • Siguientes pasos
   • Ejercicios sugeridos

Glosario General

Término (Inglés)	Término (Español)	Definición
Hexagonal Architecture	Arquitectura Hexagonal	Patrón arquitectónico creado por Alistair Cockburn que separa el dominio de negocio de los detalles técnicos
Ports and Adapters	Puertos y Adaptadores	Nombre alternativo de la arquitectura hexagonal, enfatiza el patrón de diseño subyacente
Domain	Dominio	Núcleo de la aplicación que contiene la lógica de negocio pura
Port	Puerto	Interface que define cómo interactúa el dominio con el exterior
Adapter	Adaptador	Implementación concreta de un puerto que conecta con tecnologías específicas
Primary Port	Puerto Primario	Interface que permite al exterior invocar el dominio (driving)
Secondary Port	Puerto Secundario	Interface que el dominio usa para comunicarse con el exterior (driven)
Use Case	Caso de Uso	Orquestación de la lógica de negocio para un objetivo específico
Entity	Entidad	Objeto del dominio con identidad única y ciclo de vida
Value Object	Objeto de Valor	Objeto inmutable definido solo por sus atributos
Repository	Repositorio	Patrón para abstraer la persistencia de agregados
Aggregate	Agregado	Grupo de entidades y value objects tratados como una unidad

Requisitos Previos

• Conocimientos básicos de TypeScript/JavaScript
• Comprensión de POO (clases, interfaces, herencia)
• Familiaridad con patrones de diseño básicos
• Experiencia con desarrollo de aplicaciones

Referencias Originales

• Alistair Cockburn - Hexagonal Architecture (2005)
• Netflix Tech Blog - Ready for changes with Hexagonal Architecture
• Tom Hombergs - Get Your Hands Dirty on Clean Architecture
• Martin Fowler - Ports and Adapters