Arquitectura hexagonal: puertos y adaptadores

La arquitectura hexagonal impulsa aplicaciones más claras y mantenibles al separar qué hace la aplicación de cómo se conecta con el exterior. Con puertos y adaptadores, se definen límites nítidos: la lógica central se enfoca en su funcionalidad, mientras los detalles técnicos viven en los adaptadores. Resultado: desacoplamiento, tests de unidad más simples y múltiples formas de consumo sin reescribir la lógica.

¿Qué es la arquitectura hexagonal y por qué importa?

La idea central es identificar dependencias externas y aislarlas detrás de puertos. Así, la aplicación conoce su contrato funcional, no sus implementaciones. Los adaptadores cumplen el rol de traducción: conectan la lógica con el mundo real.

¿Cómo funcionan los puertos?

• Son interfaces de comunicación finas con el exterior.
• Declaran funcionalidades: no detalles de transporte o formato.
• Permiten múltiples consumidores del mismo servicio.

¿Qué hacen los adaptadores?

• Implementan el “cómo” conectar: protocolos, formatos y destinos.
• Construyen mensajes según el consumidor: HTML, JSON o XML.
• Encapsulan detalles técnicos para que la lógica no se ensucie.

¿Qué gana el equipo con este enfoque?

• Desacoplamiento: cambios en infraestructura no rompen la lógica.
• Testabilidad: tests de unidad sin base de datos ni file system reales.
• Reuso: un mismo puerto sirve a varios canales.

¿Cómo se aplica en una aplicación web?

Un ejemplo típico: un puerto de servicios expone la funcionalidad central. Distintos adaptadores consumen ese puerto y presentan la información según el canal.

¿Qué expone el puerto de servicios?

• Una interfaz única para el mundo externo.
• Servicios consumidos por un adaptador HTTP que genera páginas HTML.
• Los mismos servicios servidos por una REST API que responde en JSON o XML.

¿Cómo se generan reportes en CSV?

• Se define un puerto de reportes independiente.
• Un adaptador consume ese puerto y produce archivos CSV descargables.
• El adaptador conoce el detalle CSV; la aplicación no lo necesita.

¿Cómo se integra almacenamiento y base de datos?

• Un puerto representa el acceso a datos.
• Adaptadores conectan a un file system local o a un servicio remoto como Amazon S3.
• Otro adaptador se encarga de la base: SQL o NoSQL sin acoplar la lógica.

¿Qué ventajas y riesgos de diseño debes considerar?

Esta arquitectura brinda control y claridad, pero exige disciplina. Si un puerto filtra detalles técnicos, se rompen las reglas y todo el ecosistema lo sufre.

¿Por qué facilita las pruebas?

• La lógica no depende de implementaciones reales.
• Los puertos permiten dobles de prueba simples.
• Se aislan errores a nivel de adaptadores.

¿Qué errores de diseño evitar?

• Hacer que un puerto “sepa” de file system o formatos.
• Obligar a un consumidor (por ejemplo, REST) a leer y desarmar archivos.
• Mezclar contratos funcionales con decisiones de infraestructura.

¿Cuándo optar por algo más simple primero?

• Si se necesita iterar más rápido al inicio.
• Cuando el dominio aún está en descubrimiento.
• Con la idea de evolucionar luego a hexagonal para ganar mantenibilidad.

¿Tienes dudas o quieres compartir cómo modelas tus puertos y adaptadores? Escribe tu comentario y conversemos sobre decisiones de diseño y trade-offs en tu contexto.