Arquitectura Hexagonal: Diseño y Aplicación Práctica

Hexagonal - Puertos y adaptadores

Nos ayuda a diseñar una aplicación que tenga bien claras cuáles son sus dependencias externas, es decir, cómo se va a consumir externamente y qué necesita del mundo exterior. Esto lo hace definiendo puertos que son su capa fina de comunicación con el exterior en dónde la aplicación sólo sabe su funcionalidad, pero no el cómo, y adaptadores que se van a encargar del cómo específicamente

Está bien la teoría pero hubiese estado mucho mejor haber llevado esto a clases en un framework mvc.

Con toda esta información no se como plasmarlo en mi código php

Patrones: Hexagonal - Puertos y adaptadores

Nos ayuda a construir un patron que tiene bien claras sus dependencias externas. Esto lo hace definiendo puertos que son su capa fina con el exterior, donde la aplicación sabe su funcionalidad pero no el como. Y existen adaptares que se encargarán del “Como” especificamente.

---

Si la App necesita acceso al file system o a la BD va a modelar un puerto que represente a sus datos y luego va a modelar un adaptador. Esta aplicación permite hacer tests de unidades muy fácilmente.

---

Ejemplos: Aplicaciones WEB

Yo les comparto este video de youtube que me ayudo muchísimo a entender el tema de la arquitectura hexagonal.

Esto lo comento por mera experiencia.
Esta arquitectura esta muy ligada con los ejemplos que vimos en la arquitectura de capas y MVC.
La principal diferencia que se tiene es que en le hexagonal requiere que el dominio declare los puertos (generalmente como interfaces lo cual abstrae por completo el problema de separar la implementación de la abtracción).
Son muy parecidos ya que en ambos separas las responsabilidades y en ambos casos el dominio desconoce los detalles de:

• Quien lo llama o usa
• Cómo se manejan los datos.
• Como se ejecutan ciertos procesos (ej, envío de email o notificaciones)
• Como se muestra la información (Por ejemplo, los servicios devuelve Array<Obj> y quien llamo al servicio [controller por ejemplo] generan un JSON o un CSV).

Para mi es una de las arquitecturas más limpias. El principal inconveniente es que genera muchos archivos y se vuelve complicado de manejar. Además de que es más complicado de implementar en lenguajes que no tienen validación de tipo de datos.

Como nota final, eta arquitectura es muy buena cuando tiene servicios complejos. Si estas realizando un API CRUD muy sencilla quizá sea un overkill manejar esta arquitectura

Hola estos son un ejemplo de scaffolding que me parecieron interesantes (spring boot) usando este tipo de arquitectura hexagonal:

application/
rest/ # el controller
request/ # aquí irán todos los objetos dto para la petición
response / # los dto de la response
domain/
repository/ # interfaz del repository
service/
Exception.java
Foo.java
infrastructure/
configuration/ # La configuración de las distintas bases de datos (MongoDB, Cassandra…).
# También configuración de los Beans (Services en este caso).
repository/ # Implementación de la interfaz repository para los distintos repositorios, también mappers, Modelo de datos, etc.
Application.java

Aquí una implementación con Angular y nestjs [jimyhdolores/hexagonal-architecture-nestjs-angular](https://github.com/jimyhdolores/hexagonal-architecture-nestjs-angular/tree/main)

El patrón hexagonal, también conocido como patrón de puertos y adaptadores, es un enfoque arquitectónico que busca desacoplar la lógica de negocio de las interacciones con el mundo exterior, como interfaces de usuario, servicios externos, bases de datos, etc. Esta separación permite que el núcleo del sistema sea más resistente a cambios y más fácil de probar. #### Estructura del Patrón 1. **Núcleo de la Aplicación**: * Contiene la lógica del negocio y es independiente de cualquier tecnología específica. * Se enfoca en las reglas y procesos del dominio. 2. **Puertos**: * Son interfaces que definen cómo interactuar con el núcleo de la aplicación. * Pueden ser de entrada (para recibir acciones) o de salida (para enviar datos a sistemas externos). 3. **Adaptadores**: * Implementan los puertos y traducen las interacciones entre el núcleo y el mundo exterior. * Pueden ser de diferentes tipos, como adaptadores de interfaz de usuario, adaptadores de base de datos, APIs, etc. #### Ventajas del Patrón Hexagonal * **Independencia Tecnológica**: Facilita cambios en la infraestructura, como cambiar la base de datos o la interfaz de usuario, sin modificar la lógica de negocio. * **Facilidad en Pruebas**: Permite realizar pruebas unitarias y de integración de manera más efectiva al poder simular adaptadores. * **Flexibilidad**: Hace sencillo agregar o cambiar adaptadores, permitiendo la adaptación a nuevas necesidades de negocio rápidamente. * **Estructura Clara**: Ofrece una organización clara y modular del código, facilitando el entendimiento del flujo de datos. * **Separación de Preocupaciones**: Fomenta buenas prácticas de diseño de software al separar claramente la lógica de negocio de los detalles de implementación. #### Desventajas del Patrón Hexagonal * **Complejidad Inicial**: Puede ser excesivo para aplicaciones pequeñas, donde los beneficios no justifican la sobrecarga arquitectónica. * **Curva de Aprendizaje**: Desarrolladores no familiarizados con el patrón pueden tardar en adaptarse y entender su estructura. * **Diseño del Núcleo**: Requiere un diseño sólido del núcleo desde el principio, donde los errores pueden ser difíciles de corregir más adelante. * **Sobrecarga de Adaptadores**: La necesidad de múltiples adaptadores para diversas tecnologías puede aumentar la complejidad del código. #### Consideraciones Adicionales El patrón hexagonal es especialmente útil en sistemas complejos donde la lógica de negocio es fundamental. Su enfoque en la separación de preocupaciones y el desacoplamiento de componentes permite una mayor flexibilidad y adaptabilidad ante cambios. Sin embargo, es importante evaluar su idoneidad en función del tamaño y las necesidades del proyecto para evitar una implementación innecesariamente compleja.

La arquitectura Hexagonal se enfoca en aislar el **núcleo de negocio** de la infraestructura, facilitando la **extensibilidad** y **mantenibilidad** del sistema al poder agregar o cambiar adaptadores sin afectar la lógica principal. Vamos a usar un ejemplo de un **sistema de pedidos** para un e-commerce, donde se gestionan los pedidos y su procesamiento. ``` /order-management-system │ ├── /src │ ├── /application # Capa de aplicación (casos de uso) │ │ ├── /ports # Interfaces (puertos) que definen los casos de uso │ │ │ ├── /inbound # Puertos de entrada (interacción del mundo externo) │ │ │ │ └── OrderService.ts # Ejemplo de puerto de entrada para gestionar pedidos │ │ │ └── /outbound # Puertos de salida (interacción con el exterior) │ │ │ └── OrderRepository.ts# Ejemplo de puerto de salida para repositorios de pedidos │ │ ├── /services # Implementación de los casos de uso │ │ │ └── OrderManagementService.ts # Ejemplo de implementación de la gestión de pedidos │ │ └── /exceptions # Excepciones de la aplicación │ │ │ ├── /domain # Capa de dominio (lógica de negocio) │ │ ├── /models # Modelos y entidades del dominio │ │ │ └── Order.ts # Ejemplo de la entidad Pedido │ │ └── /services # Servicios de dominio (reglas y políticas de negocio) │ │ └── OrderProcessingService.ts # Ejemplo de lógica de procesamiento de pedidos │ │ │ ├── /adapters # Adaptadores (interfaz con el mundo exterior) │ │ ├── /inbound # Adaptadores de entrada │ │ │ ├── /rest # Adaptador para REST API │ │ │ │ └── OrderController.ts# Controlador de pedidos expuesto en API REST │ │ │ ├── /cli # Adaptador para CLI (Command Line Interface) │ │ │ │ └── OrderCLI.ts # Interfaz de línea de comandos para gestionar pedidos │ │ │ └── /events # Adaptador para escuchar eventos externos │ │ │ └── OrderEventListener.ts # Listener de eventos para la gestión de pedidos │ │ ├── /outbound # Adaptadores de salida │ │ │ ├── /persistence # Adaptadores para interactuar con la base de datos │ │ │ │ └── OrderRepositoryImpl.ts # Implementación del repositorio de pedidos │ │ │ ├── /message-queue # Adaptador para interactuar con un sistema de mensajería │ │ │ │ └── OrderEventPublisher.ts # Publicación de eventos en un message broker │ │ │ └── /email # Adaptador para servicios de email │ │ │ └── OrderEmailSender.ts # Servicio para enviar notificaciones por email │ │ │ └── /config # Archivos de configuración del sistema │ ├── /application.yml # Configuraciones de la aplicación (entorno, puertos, etc.) │ ├── /db.config.ts # Configuraciones de base de datos │ └── /message-queue.config.ts # Configuración para el sistema de mensajería │ ├── /tests # Pruebas unitarias y de integración │ ├── /application # Pruebas de la capa de aplicación │ ├── /domain # Pruebas de la lógica de dominio │ ├── /adapters # Pruebas de los adaptadores │ └── /integration # Pruebas de integración │ ├── /docs # Documentación del proyecto │ ├── /architecture.md # Documentación de la arquitectura Hexagonal │ ├── /use-cases.md # Descripción de los casos de uso │ └── /api-spec.md # Especificaciones de la API │ ├── /infrastructure # Configuración y scripts de infraestructura │ ├── /docker # Configuración para contenedores Docker │ │ ├── Dockerfile # Archivo Dockerfile para construir la imagen │ │ └── docker-compose.yml # Archivo para orquestación con Docker Compose │ ├── /kubernetes # Configuración para despliegue en Kubernetes │ ├── /db # Scripts de inicialización de base de datos │ └── /messaging # Configuraciones del sistema de mensajería (RabbitMQ, Kafka, etc.) │ ├── /scripts # Scripts auxiliares para automatizar tareas │ └── init-db.sh # Script para inicializar la base de datos │ ├── /logs # Carpeta para los archivos de log │ └── application.log # Archivo de log de la aplicación │ ├── /build # Archivos generados por el proceso de build │ ├── /node\_modules # Dependencias del proyecto (si es un proyecto Node.js) │ ├── package.json # Dependencias y scripts del proyecto (si es Node.js) ├── README.md # Documentación principal del proyecto └── .gitignore # Archivos y carpetas que Git debe ignorar ``` Explicación de la Estructura 1. **Application (Capa de aplicación)**: * Aquí se definen los **puertos** (interfaces) de entrada y salida, que representan la abstracción entre la lógica de la aplicación y los adaptadores. * **Puertos de entrada**: Representan las interfaces de interacción con el usuario o sistemas externos (como servicios REST o CLI). * **Puertos de salida**: Interfaces que se conectan a componentes externos como bases de datos o sistemas de mensajería. 2. **Domain (Capa de dominio)**: * Aquí se encuentra la **lógica de negocio pura**. Incluye entidades, modelos, y servicios de dominio que contienen las reglas de negocio. Esta capa no tiene dependencia de infraestructura, lo que la hace muy reutilizable y fácil de testear. 3. **Adapters (Adaptadores)**: * Estos son los **adaptadores que conectan el núcleo del sistema (application/domain)** con el mundo exterior. Incluyen: * **Adaptadores de entrada**: REST APIs, CLI, listeners de eventos, etc. * **Adaptadores de salida**: Implementaciones concretas de los puertos de salida, como acceso a base de datos, integración con sistemas de mensajería, envío de emails, etc. 4. **Config**: * Aquí se encuentran los **archivos de configuración** de la aplicación, como configuraciones de la base de datos, sistemas de mensajería y otros servicios. 5. **Tests**: * Contiene las **pruebas unitarias e integración**. Se dividen por las capas del sistema para asegurar que cada componente funcione correctamente de forma aislada y en conjunto. 6. **Infrastructure**: * Configuración relacionada con la **infraestructura del proyecto**, como Docker, Kubernetes y scripts de base de datos. 7. **Logs**: * Carpeta destinada para almacenar los archivos de log del sistema, facilitando la auditoría y depuración. ### Ventajas de la Arquitectura Hexagonal * **Independencia de la infraestructura**: La lógica del negocio está completamente aislada de los detalles técnicos externos, lo que permite cambiar tecnologías sin afectar el núcleo del sistema. * **Facilidad de prueba**: Al estar las capas desacopladas, es sencillo escribir pruebas para la lógica de negocio sin necesidad de instanciar bases de datos o servicios externos. * **Extensibilidad**: Puedes añadir nuevos adaptadores (por ejemplo, un nuevo sistema de mensajería) sin modificar el código del núcleo. * **Mantenimiento**: Cada capa es responsable de un conjunto bien definido de tareas, lo que facilita el mantenimiento y la evolución del sistema. Este ejemplo muestra cómo se organiza un proyecto usando **arquitectura Hexagonal**, donde los componentes de la aplicación (lógica de negocio) están completamente desacoplados de las interfaces del mundo exterior (como bases de datos, APIs, o mensajería).