Saltar a contenido

Sesión 0 — El problema, los conceptos y el setup

Lo que vas a lograr: entender por qué vamos a usar hexagonal y por qué no otra arquitectura, y dejar tu entorno listo.

Parte 1 — El problema, en una historia (5 min)

Un equipo venía de un monolito en PHP. Migró a microservicios en Kotlin. Hasta ahí, la historia de éxito de cualquier charla. Pero seis meses después tenían los mismos problemas, ahora repartidos en más servidores. ¿Por qué? Porque dentro de cada microservicio copiaron la arquitectura en capas tradicional, y con ella el mismo acoplamiento.

Tres dolores se repetían:

  1. Cambiar una pasarela de pago rompía el negocio. El proveedor vivía metido en la lógica.
  2. Probar el negocio pedía levantar todo. Spring, base de datos, a veces colas. Nadie corría esos tests.
  3. Nadie encontraba la regla. Estaba enterrada entre anotaciones y llamadas externas.

La conclusión: el problema no era el monolito, era el acoplamiento. Y eso es lo que la arquitectura hexagonal viene a resolver.

Parte 2 — Por qué hexagonal y no otra (5 min)

Antes de elegir, mirá las opciones:

  • Capas tradicionales: Controller → Service → Repository. Simple, pero el negocio termina conociendo la infraestructura. Es justo lo que dolía.
  • Onion / Clean Architecture: capas concéntricas con las dependencias hacia adentro. Muy buenas, primas hermanas de hexagonal. Traen más estructura de la que a veces se necesita.
  • Hexagonal (puertos y adaptadores): mínima y simétrica. Un puerto, muchos adaptadores.

Elegimos hexagonal por tres razones:

  1. Un puerto, muchos adaptadores. Nuestro dolor eran muchas pasarelas que cambiaban. Hexagonal las modela exacto: cada proveedor es un adaptador detrás del mismo puerto.
  2. El negocio se prueba sin nada. Sin Spring, sin base de datos, en milisegundos.
  3. Independiente del framework. El dominio no conoce Spring.

Parte 3 — Los conceptos en 2 minutos

Tres zonas:

  • Dominio: el modelo de negocio y sus reglas. Kotlin puro, cero framework.
  • Aplicación: los casos de uso y los puertos. Orquesta.
  • Infraestructura: los adaptadores. REST, JPA, la pasarela. Lo que toca el mundo.
   [ REST / Vaadin ]            [ JPA / PostgreSQL ]
   [ Tests ]        →   ( DOMINIO + APLICACIÓN )   →   [ Pasarela de pago (Feign) ]
       entrada                                              salida

La regla de dependencias

Las dependencias siempre apuntan hacia adentro. Infraestructura depende de aplicación, aplicación depende de dominio, y nunca al revés.

Dos tipos de puertos:

  • Entrada (driving): lo que la app ofrece. Ejemplo: "procesar un pago".
  • Salida (driven): lo que la app necesita. Ejemplo: "cobrar con la pasarela", "guardar el pago".

Parte 4 — Lo que necesitás instalar (10 min)

Java 21

java -version

sdk install java 21-tem   # con SDKMAN

winget install EclipseAdoptium.Temurin.21.JDK

Docker

Para levantar PostgreSQL sin instalarlo a mano.

docker --version

Si no lo tenés: Docker Desktop.

IntelliJ IDEA

La Community Edition alcanza: jetbrains.com/idea. Trae Kotlin y Gradle de fábrica.

Un cliente HTTP

curl, Postman o el cliente HTTP de IntelliJ.

Parte 5 — La carpeta del repo

mkdir hexarch-kotlin-baqjug
cd hexarch-kotlin-baqjug
git init

Al final vas a tener:

hexarch-kotlin-baqjug/
  payments/        ← el servicio, sesiones 1 a 5
  provider-sim/    ← una pasarela de pago de mentira para probar, sesión 3

Por qué los dos en el mismo repo

Para que sea fácil de seguir. payments es el protagonista. provider-sim es un proveedor falso que armamos en la sesión 3 para que el Feign tenga a quién llamar sin depender de un servicio real.

Cuando estés listo, seguí a la Sesión 1.