La arquitectura hexagonal es un patrón de diseño de software limpio que separa la lógica de tu aplicación del mundo exterior usando ports y adapters. Si te interesa escribir código mantenible, escalable y fácil de probar, entender este modelo es un paso clave para tu carrera como desarrollador.

Fue propuesta por Alistair Cockburn en 2005 y desde entonces se convirtió en una de las referencias dentro de las clean architectures. Vamos a desglosarla con un ejemplo concreto: un sistema de gestión de clientes, lo que comúnmente conoces como CRM.

¿Qué es la arquitectura hexagonal y por qué se llama así?

La idea central es proteger tu aplicación (el dominio) y mantenerla aislada de detalles externos como bases de datos, interfaces gráficas o APIs. Esa aplicación se dibuja como un hexágono, no porque seis lados tengan un significado mágico, sino porque ofrece espacio visual suficiente para representar los ports y adapters alrededor.

¿Por qué un hexágono y no otra figura? Porque Alistair Cockburn buscaba una representación visual con espacio suficiente para los puertos y adaptadores. Si tu sistema tiene más o menos puertos, la arquitectura sigue siendo hexagonal.

Esta arquitectura también se conoce como ports and adapters, un nombre que describe mejor lo que realmente hace.

¿Cómo funcionan los ports y adapters en un ejemplo real?

Imagina tu CRM en el centro. A su alrededor colocas dos ports: uno que es una API de clientes y otro que es una API de persistencia o base de datos. Esos puertos son los puentes oficiales para entrar y salir de tu aplicación.

Por encima de los ports viven los adapters, encargados de traducir lo externo a algo que tu aplicación entienda. Aquí algunos ejemplos concretos:

• Una interfaz gráfica que captura clicks en botones, eventos de campos de texto y navegación, y los traduce a llamadas que entiende la API de clientes.
• Una API REST que maneja detalles propios de HTTP, conversiones a JSON o XML, y adapta esa información al mismo puerto de clientes.
• Una conexión específica a MySQL con clases que saben hablar el dialecto de esa base de datos y lo traducen al puerto de persistencia.
• Mocks para pruebas de integración, que simulan comportamientos sin tocar infraestructura real.

Fíjate en algo poderoso: si mañana quieres soportar otra base de datos o una nueva forma de interactuar, solo creas un nuevo adapter. Tu aplicación no se entera. Eso es aplicar el principio open-closed en estado puro: abierto a extensión, cerrado a modificación.

¿Cómo se aplica la regla de dependencia aquí?

La regla de dependencia dice que lo externo conoce lo interno, pero nunca al revés. Tu aplicación debe ser totalmente agnóstica de qué adapters la rodean. No sabe si la están llamando desde una interfaz gráfica, una API REST o un test automatizado, y esa ignorancia es justamente lo que la hace flexible.

Si tu dominio empieza a saber sobre MySQL o sobre HTTP, ya rompiste la arquitectura.

¿Qué diferencia hay entre actores primarios y secundarios?

Dentro de la arquitectura hexagonal aparecen dos conceptos complementarios muy útiles para entender el flujo de información.

Actores primarios: los que inician la acción

Los actores primarios son los adapters capaces de iniciar interacciones con el sistema. Son elementos activos. Cuando un usuario envía un formulario desde la interfaz gráfica, esa acción dispara un proceso que atraviesa el puerto y llega a tu aplicación.

La interfaz gráfica y la API REST suelen jugar este rol: golpean la puerta y arrancan el flujo.

Actores secundarios: los que son notificados

Los actores secundarios son adapters que reciben instrucciones desde la aplicación. No inician nada, son parte de un flujo guiado.

¿Qué es un actor secundario en arquitectura hexagonal? Es un adaptador al que la aplicación le pide ejecutar algo, como guardar datos o correr una query. Nunca inicia la interacción, solo responde.

Siguiendo el ejemplo: la interfaz envía un formulario (actor primario), entra a la aplicación, y dentro del proceso la aplicación le pide a la base de datos guardar la información. Esa base de datos actúa como secundaria, simplemente cumple la orden.

¿Qué conceptos clave debes recordar de esta arquitectura?

Antes de aplicarla en tu próximo proyecto, ten presente lo siguiente:

• Aplicación o dominio [0:18]: el núcleo aislado que contiene la lógica de negocio.
• Ports [0:38]: contratos o interfaces que definen cómo entrar y salir del dominio.
• Adapters [1:18]: traductores entre el mundo externo y los puertos.
• Principio open-closed [2:18]: extiende con nuevos adapters sin tocar el dominio.
• Regla de dependencia [3:08]: lo externo depende de lo interno, nunca al revés.
• Actores primarios [3:30]: inician interacciones, como una UI o una API REST.
• Actores secundarios [4:00]: son notificados y guiados, como una base de datos.
• Origen [4:38]: Alistair Cockburn, 2005, también conocida como ports and adapters.

Ahora viene tu turno. Piensa en la última aplicación en la que trabajaste o estás trabajando ahora mismo. ¿Cuál sería un ejemplo de port y cuál un ejemplo de adapter en ese sistema? Déjanos tu respuesta en los comentarios y empieza a entrenar el ojo para distinguir qué pertenece al dominio y qué debe vivir en una capa externa.