Tu app doméstica enciende las luces desde el móvil, pero cada cambio de base de datos obliga a tocar también la lógica de automatización. La arquitectura hexagonal suele evitar ese acoplamiento al separar las reglas del hogar conectado de las tecnologías que las rodean, aunque añadir puertos y adaptadores sin una necesidad clara también puede complicar el proyecto.

La lógica del hogar debe poder funcionar sin depender de una marca o tecnología
- El núcleo contiene las reglas y los casos de uso de la aplicación.
- Los puertos definen cómo se comunica ese núcleo con el exterior.
- Los adaptadores conectan esos puertos con una API, una base de datos o un dispositivo.
- El hexágono no tiene seis lados obligatorios; el nombre es una representación visual.
- La complejidad adicional se justifica cuando hay integraciones que pueden cambiar o varias formas de usar el sistema.
El núcleo decide qué debe ocurrir y los adaptadores se ocupan de la tecnología
Imagina que una regla enciende la calefacción cuando la temperatura baja de cierto valor. La regla pertenece al núcleo de la aplicación; leer el sensor, recibir una orden desde el móvil o enviar una señal al termostato son tareas de comunicación con el exterior.
La arquitectura hexagonal, también llamada puertos y adaptadores, organiza esa frontera. Un puerto es un contrato que expresa qué necesita la aplicación; un adaptador traduce ese contrato a una tecnología concreta, como una API HTTP, una base de datos o un protocolo de dispositivo. Así, el dominio puede conservar sus reglas aunque cambie la integración.
La dirección de las dependencias es la pista más útil para revisar el diseño: el código externo depende de los contratos del núcleo, no al revés. Si una clase de dominio importa directamente una biblioteca del fabricante del termostato, la frontera se ha vuelto borrosa.
El hexágono no exige seis puertos ni seis componentes
El dibujo puede confundir: no hay que rellenar seis lados ni crear seis módulos. El hexágono sirve para representar un núcleo con varios puntos de conexión, y el propio texto de Alistair Cockburn sobre puertos y adaptadores explica que la forma no impone una cantidad fija de puertos.
Un puerto puede tener varios adaptadores. Por ejemplo, el mismo caso de uso para consultar el estado de una vivienda podría activarse desde una aplicación móvil, una consola de administración o una prueba automatizada. La lógica central no necesita saber cuál de ellos inició la consulta.
Creo que este detalle evita un error habitual: diseñar el diagrama como si fuera una plantilla rígida. El dibujo ayuda a razonar sobre límites; la estructura real debe seguir las necesidades del sistema.
Una regla doméstica muestra dónde van los puertos y adaptadores
Supón que la aplicación activa una alarma cuando un sensor detecta una apertura mientras el modo de seguridad está encendido. El caso de uso decide qué hacer; los componentes conectados solo transportan datos hacia dentro o ejecutan una acción hacia fuera.
| Elemento | Ejemplo en la app doméstica | Responsabilidad |
|---|---|---|
| Dominio | Regla de alarma y estado del modo de seguridad | Aplicar las reglas del producto |
| Puerto de entrada | Orden «activar modo noche» | Definir una operación que la aplicación ofrece |
| Adaptador de entrada | Controlador de la app móvil | Convertir una petición externa en una llamada al caso de uso |
| Puerto de salida | Contrato para consultar sensores o enviar avisos | Expresar qué servicio requiere la aplicación |
| Adaptador de salida | Integración con el fabricante, la base de datos o el servicio de notificaciones | Traducir el contrato a una tecnología concreta |
Esta separación también permite cambiar cómo se envía una alerta sin reescribir la regla que la activa. La guía de arquitectura hexagonal de AWS describe el mismo principio mediante componentes intercambiables, como una API, una base de datos o servicios externos.
Las pruebas del núcleo pueden usar adaptadores en memoria
Para probar una regla de automatización no hace falta conectar cada vez el sensor físico ni levantar la base de datos de producción. Puedes implementar un adaptador sencillo en memoria que entregue lecturas controladas y registre las órdenes emitidas; así compruebas el comportamiento del caso de uso sin depender de la infraestructura.
Pero una prueba aislada no demuestra que el adaptador real respete el contrato. Si el adaptador de base de datos guarda la temperatura en una unidad distinta o interpreta de otro modo un valor ausente, la prueba del núcleo podría pasar mientras falla la integración. Para cubrir ese hueco, ejecuta una misma batería de pruebas de contrato contra el adaptador en memoria y contra el adaptador real con datos de prueba.
| Situación | Riesgo probable | Qué hacer |
|---|---|---|
| La regla falla con un valor del sensor simulado | El caso de uso o la lógica del dominio no cumple la regla esperada | Revisar la prueba del núcleo antes de investigar el hardware |
| La prueba en memoria pasa, pero el sistema falla con el dispositivo real | El adaptador traduce mal los datos o la respuesta del fabricante | Probar el adaptador real y verificar que cumple el contrato del puerto |
| El núcleo funciona, pero el sistema desplegado no recibe órdenes | Puede haber un error de configuración o cableado entre componentes | Ejecutar pruebas de integración y de extremo a extremo en un entorno de prueba |
La arquitectura facilita aislar pruebas, pero no elimina las pruebas de integración: una simulación no confirma que los permisos, la configuración o la comunicación con el dispositivo funcionen en el entorno real.
Si solo hay una integración estable, quizá baste una estructura sencilla
Separar cada operación en interfaces, casos de uso y adaptadores añade código que alguien tendrá que mantener. Según la guía de AWS sobre el patrón, esa sobrecarga se justifica mejor cuando existen varias fuentes de entrada o destinos de salida, o cuando la tecnología de almacenamiento puede cambiar.
Como criterio práctico, si la aplicación tiene una sola interfaz, una integración estable y reglas pequeñas, empieza con límites claros y añade puertos donde aparezca una dependencia externa que quieras aislar o sustituir. Si los mismos casos de uso deben atender una app móvil, automatizaciones y una consola, o si integras varias marcas de dispositivos, la separación ofrece una ventaja más visible.
- Una interfaz y una integración estable: evita crear adaptadores por rutina; conserva una separación sencilla entre reglas y tecnología.
- Varios canales o proveedores intercambiables: define puertos para las dependencias externas que puedan variar.
- Reglas de negocio que cambian a menudo: protege el dominio para probarlo sin arrancar toda la infraestructura.
La señal de exceso de diseño también es concreta: si un puerto solo duplica una llamada sin aislar una decisión de negocio ni una tecnología sustituible, probablemente añade una capa sin resolver un problema. En una app doméstica, empezaría por independizar las reglas de automatización y las integraciones de dispositivos; ampliaría el patrón cuando aparezcan nuevos canales o proveedores.
La mejor arquitectura deja las reglas listas para cambiar de dispositivo
Cuando una automatización depende directamente de una marca, cambiar el sensor puede arrastrar cambios por todo el sistema. Con puertos bien definidos, el dispositivo queda en el borde y el comportamiento de la vivienda permanece dentro del núcleo.
Por eso, la arquitectura hexagonal funciona mejor como una frontera útil que como una colección obligatoria de carpetas e interfaces. Protege las reglas que quieres conservar, y evita construir adaptadores para componentes que no necesitas cambiar ni probar por separado.