Arquitectura Hexagonal

Este artículo es una explicación de conceptos sobre Arquitectura Hexagonal (Ports and Adapters), incluyendo preguntas típicas de examen, puntos clave de repaso y etiquetas para recordar.

¿Qué es la Arquitectura Hexagonal?

La Arquitectura Hexagonal (también llamada Ports and Adapters) es un enfoque arquitectónico que separa estrictamente el núcleo del negocio (dominio / casos de uso) de las dependencias externas, como:

• Interfaz (web, mobile, CLI)
• Base de datos
• Message Broker
• APIs externas

La idea fundamental: el núcleo define qué necesita (puertos/interfaces). La infraestructura proporciona implementaciones intercambiables (adaptadores).

Los componentes: dominio, puertos, adaptadores

Núcleo del dominio

En el centro está la lógica de negocio:

• Entidades / Value Objects
• Casos de uso / Application Services
• Reglas de negocio

Puertos

Los puertos son interfaces que establecen la dirección de la dependencia:

• Puertos de entrada: lo que la aplicación ofrece (casos de uso, comandos)
• Puertos de salida: lo que la aplicación necesita (repositorios, pagos, correo, logging)

Adaptadores

Los adaptadores conectan puertos con tecnología concreta:

• Adaptadores de entrada: controladores REST, resolvedores GraphQL, CLI, planificadores
• Adaptadores de salida: repositorio de BD, cliente HTTP, caché, productor de mensajes

¿Por qué es útil? (Ventajas)

• Testabilidad: la lógica del núcleo se puede probar sin BD/HTTP (mocks/fakes en puertos)
• Intercambiabilidad: los cambios de tecnología afectan adaptadores, no el núcleo
• Bajo acoplamiento: menos dependencias de frameworks en el código de dominio
• Responsabilidades claras: límites del sistema bien definidos

Desventajas típicas / Trade-offs

• Más abstracción (puertos/adaptadores) = más artefactos
• Mayor esfuerzo inicial (wiring, DI, mapping)
• Curva de aprendizaje para equipos que desarrollan “directamente contra frameworks”

Ejemplo práctico mini (simplificado)

Idea

Un caso de uso “pagar pedido” solo conoce puertos. Un adaptador Stripe o un adaptador de BD pueden intercambiarse después.

// Inbound Port
export interface PayOrderUseCase {
  pay(orderId: string): Promise<string>;
}

// Outbound Ports
export interface OrderRepositoryPort {
  findById(orderId: string): Promise<any>;
  save(order: any): Promise<void>;
}

export interface PaymentProviderPort {
  charge(amountInCents: number, customerId: string): Promise<{ transactionId: string }>;
}

Relación con Design Patterns

La arquitectura hexagonal utiliza varios Design Patterns conocidos:

Adapter Pattern

El patrón Adapter clásico se aplica sistemáticamente aquí. En lugar de adaptadores aislados, implementas capas completas de adaptadores para conceptos técnicos (base de datos, HTTP, mensajería).

Strategy Pattern

Los puertos de salida definen estrategias para acceder a la infraestructura. El núcleo trabaja contra la interfaz de estrategia, y las implementaciones concretas pueden intercambiarse.

Dependency Injection

La arquitectura hexagonal se basa en Dependency Injection. Los adaptadores se inyectan en el núcleo, no al revés. Esto permite bajo acoplamiento y fácil testabilidad.

Facade Pattern

Los adaptadores de entrada pueden actuar como fachadas para casos de uso complejos. Encapsulan la interacción con el núcleo del dominio.

Acoplamiento en la arquitectura hexagonal

Acoplamiento fuerte (a evitar)

Con acoplamiento fuerte, la lógica de negocio depende directamente de tecnologías concretas. Un cambio de base de datos o actualización de framework requiere modificaciones en el núcleo de la aplicación.

Acoplamiento débil (el objetivo)

La arquitectura hexagonal impone bajo acoplamiento mediante puertos. El núcleo solo conoce interfaces, no implementaciones. Esto permite:

• Intercambio de adaptadores sin cambios en el núcleo
• Desarrollo paralelo de dominio e infraestructura
• Pruebas simples con implementaciones mock

Direcciones de acoplamiento

La dirección de dependencia siempre va de fuera hacia adentro. Los adaptadores conocen el núcleo a través de puertos, pero el núcleo no conoce adaptadores.

Preguntas típicas de examen (con respuesta breve)

1. ¿Cuál es el objetivo de la arquitectura hexagonal? Desacoplar la lógica de negocio de los detalles técnicos mediante puertos y adaptadores.

2. Diferencia entre adaptadores de entrada y salida. Los adaptadores de entrada traen solicitudes al núcleo, los de salida implementan acceso a infraestructura.

3. ¿Cómo se implementa la inversión de dependencias aquí? El núcleo define puertos (interfaces), la infraestructura los implementa.

4. ¿Por qué es relevante para exámenes? Puedes justificar decisiones arquitectónicas con testabilidad, mantenibilidad e intercambiabilidad.

5. ¿Qué rol juegan los puertos en la testabilidad? Los puertos permiten implementaciones mock para pruebas unitarias sin infraestructura real.

6. ¿En qué se diferencia de Clean Architecture? La arquitectura hexagonal es un enfoque específico de Clean Architecture enfocado en puertos y adaptadores.

7. ¿Qué sucede si cambias de base de datos en arquitectura hexagonal? Solo el adaptador de BD necesita reimplementarse, el núcleo del dominio permanece intacto.

8. ¿Qué responsabilidad tiene un adaptador de entrada? Recibe solicitudes externas y las envía al núcleo del dominio.

9. ¿Qué responsabilidad tiene un adaptador de salida? Implementa interfaces técnicas para el núcleo del dominio (base de datos, HTTP, etc.).

10. ¿Cómo se implementa el Dependency Inversion Principle? El núcleo del dominio define interfaces, los adaptadores implementan estas interfaces.

11. ¿Qué significa “Technology Independence”? La lógica de negocio es independiente de frameworks y bases de datos concretos.

12. ¿Qué desventajas tiene la arquitectura hexagonal? Mayor esfuerzo inicial, más capas de abstracción, curva de aprendizaje más pronunciada.

13. ¿Cuántos puertos puede tener una aplicación? Cualquier número, típicamente un puerto por caso de uso o por interfaz externa.

14. ¿Cuál es la diferencia entre puerto y adaptador? Puerto es la interfaz (interface), adaptador es la implementación concreta.

15. ¿Cómo se prueba el núcleo del dominio? Mediante adaptadores mock en puertos, sin componentes reales de infraestructura.

16. ¿Qué frameworks soportan arquitectura hexagonal? Spring Boot, .NET Core, Node.js con contenedores de inyección de dependencias.

17. ¿Qué es un “hexágono” en este contexto? Representación simbólica del núcleo del dominio con puertos en los lados.

18. ¿Cómo se modelan los casos de uso en arquitectura hexagonal? Como puertos de entrada con implementaciones correspondientes en el núcleo del dominio.

19. ¿Qué tipo de acoplamiento se evita? Acoplamiento fuerte entre lógica de negocio e implementaciones técnicas.

20. ¿Cómo se aplica el Adapter Pattern aquí? Sistemáticamente para todas las dependencias externas de la aplicación.

21. ¿Cuáles son adaptadores de entrada típicos? Controladores REST, resolvedores GraphQL, comandos CLI, oyentes de mensajes.

22. ¿Cuáles son adaptadores de salida típicos? Repositorios de base de datos, clientes HTTP, implementaciones de caché, productores de mensajes.

23. ¿Cómo se permite el desarrollo paralelo? El núcleo del dominio y los adaptadores pueden desarrollarse de forma independiente.

24. ¿Qué rol juega la inyección de dependencias? Conecta adaptadores con puertos en tiempo de ejecución y permite bajo acoplamiento.

25. ¿Cuándo merece la pena arquitectura hexagonal? En proyectos a largo plazo con cambios frecuentes y altos requisitos de pruebas.

26. ¿Cómo se protegen las reglas de negocio? Mediante capas de abstracción que previenen acceso directo desde el exterior.

27. ¿Qué significa “Infrastructure doesn’t matter”? La lógica de negocio funciona independientemente de la infraestructura elegida.

28. ¿Cómo se integra un nuevo framework de UI? Mediante un nuevo adaptador de entrada que usa puertos existentes.

29. ¿Qué estrategias de prueba se soportan? Pruebas unitarias con mocks, pruebas de integración con adaptadores reales, pruebas end-to-end.

30. ¿Cómo se mejora la mantenibilidad? Mediante separación clara de lógica de negocio y detalles técnicos.

Datos importantes para la comprensión

Desarrollo histórico

• 2005: Alistair Cockburn acuña el término “Hexagonal Architecture”
• Nombres alternativos: Ports and Adapters Pattern
• Objetivo: Proteger la lógica de negocio de cambios tecnológicos

Principios clave

• Dependency Inversion: Las dependencias van de fuera hacia adentro
• Single Responsibility: Cada adaptador tiene una tarea técnica
• Open/Closed: Los puertos están abiertos para extensión, cerrados para cambio

Tamaños típicos de proyectos

• Pequeño a mediano: 5-20 puertos, 10-50 adaptadores
• Sistemas grandes: 50+ puertos, 100+ adaptadores
• Microservicios: 3-10 puertos por servicio

Duración de implementación

• Esfuerzo inicial: 20-30% más tiempo que arquitectura tradicional
• Amortización: Después de 6-12 meses mediante cambios más rápidos
• Velocidad de pruebas: Pruebas unitarias 10-100x más rápidas que pruebas de integración

Soporte tecnológico

• Java: Spring Boot con @Component y @Autowired
• .NET: Contenedor de inyección de dependencias
• TypeScript/Node.js: Inversify, TypeDI o DI manual
• Python: FastAPI con inyección de dependencias

Criterios de éxito

• Cobertura de pruebas: >90% alcanzable en el núcleo del dominio
• Velocidad de cambios: Implementación de nuevas funcionalidades 50-80% más rápida
• Costos de mantenimiento: 30-50% menores que en arquitecturas monolíticas

Errores frecuentes

• Demasiados puertos: La sobreabstracción lleva a complejidad
• Delimitación incorrecta: Lógica de negocio desplazada a adaptadores
• Ignorar pruebas: Renunciar a adaptadores mock reduce las ventajas

La arquitectura hexagonal es especialmente adecuada cuando priorizas mantenibilidad a largo plazo, buenas pruebas e independencia tecnológica.

Artículos profundizados sobre el tema

La arquitectura hexagonal se basa en conceptos fundamentales del desarrollo de software. Para aprovechar todo el potencial de este patrón arquitectónico, los conocimientos en áreas relacionadas son esenciales. Los Design Patterns forman la base de muchos enfoques arquitectónicos, mientras que el diseño de software sólido respalda la toma de decisiones al elegir arquitecturas apropiadas. Los siguientes artículos te ayudan a aprender las bases necesarias y situar la arquitectura hexagonal en el contexto del desarrollo de software moderno.

Arquitectura y Design Patterns

• Fundamentos de Design Patterns (GoF) - Comprende los fundamentos de los patrones de diseño que se aplican en arquitectura hexagonal
• Creational Patterns (Singleton, Factory, Builder, Prototype, Abstract Factory) - Los patrones de creación son centrales para la implementación de adaptadores y factories
• Catálogo de Design Patterns - Descripción completa de todos los patrones importantes con ejemplos prácticos

Arquitectura de software y diseño

• Fundamentos del Software Design - Aprende los principios del buen diseño de software que subyacen a la arquitectura hexagonal
• Diagramas de clases UML - Visualiza la arquitectura hexagonal con diagramas UML

Aplicación práctica

• Hackathons y Coding Challenges 2026 - Aplica tus conocimientos en proyectos prácticos y prueba la arquitectura hexagonal en escenarios reales