Arquitectura hexagonal, el post que no sabías que necesitabas y que te ayuda a separar todo

Hola amante del código limpio y de las arquitecturas modernas,

En el post de hoy vamos a seguir con la serie de arquitecturas y vamos a hablar por fín de una de las más famosas:

(Si… esa que ahora te preguntan en cada entrevista de trabajo, aunque no se use en casi ningún sitio)

Así que… aunque no la estés usando, este post te interesa, aunque solo sea para explicarla en tu siguiente entrevista de trabajo.

Y tranquilo, porque te lo voy a explicar todo con un ejemplo sencillito, de esos que me gustan a mí, para que te quede todo claro.

Pero… primero, como siempre…

¿Qué es esto de arquitectura hexagonal?

Pues mira, la idea principal es:

💡 Separar tu lógica de negocio (la parte importante) del mundo exterior.

¿Y qué es el “mundo exterior”?

👉 Bases de datos, APIs, colas de mensajes, interfaces gráficas, frameworks, etc.

-“Vale… lo entiendo… pero que tiene que ver esto con un polígono hexagonal?”

Mira, muy fácil.

Tienes que visualizar tu aplicación como un hexágono, el dominio o lo que es tu lógica de negocio está en el centro, y cada lado es una puerta de entrada/salida (un “puerto”) que se conecta con un adaptador.

-“Pero… y por qué un hexágono y no otra forma…”

Bueno… eso ya se lo tendríamos que preguntar al que lo inventó… mientras tanto, quiero que te quedes solo con 2 conceptos:

• 📥 Entrada: REST, CLI, mensajería…

• 📤 Salida: repositorios, emails, servicios externos…

-“Es que yo lo veo mejor en el código”

Bueno, tranquilo, esto era para aclarar los conceptos básicos y ahora nos ponemos manos a la obra con el código.

Y para ello, vamos a montar una mini mini aplicación para crear pedidos.

---

🧠 1. Dominio (el centro del hexágono y nuestra lógica)

public class Pedido {
    private final String producto;
    private final int cantidad;

    public Pedido(String producto, int cantidad) {
        if (cantidad <= 0) throw new IllegalArgumentException("Cantidad inválida");
        this.producto = producto;
        this.cantidad = cantidad;
    }

    // getters y lógica del negocio
}

🧃 2. Puerto de salida (interfaz que define la persistencia)

public interface PedidoRepository {
    void guardar(Pedido pedido);
}

⚙️ 3. Caso de uso (orquesta la acción)

public class CrearPedidoUseCase {
    private final PedidoRepository repository;

    public CrearPedidoUseCase(PedidoRepository repository) {
        this.repository = repository;
    }

    public void ejecutar(String producto, int cantidad) {
        Pedido pedido = new Pedido(producto, cantidad);
        repository.guardar(pedido);
    }
}

🧱 4. Adaptador de salida

Implementamos el puerto con Spring Data, pero la gracia de esto es que podría ser con cualquiera:

@Repository
public class PedidoRepositoryJpa implements PedidoRepository {

    private final JpaPedidoRepository jpa;

    public PedidoRepositoryJpa(JpaPedidoRepository jpa) {
        this.jpa = jpa;
    }

    @Override
    public void guardar(Pedido pedido) {
        jpa.save(new PedidoEntity(pedido.getProducto(), pedido.getCantidad()));
    }
}

🌐 5. Adaptador de entrada (controlador REST)

Igual que en el adaptador de salida, aquí definimos un servicio REST, pero también podría ser el que queramos.

@RestController
@RequestMapping("/pedidos")
public class PedidoController {

    private final CrearPedidoUseCase useCase;

    public PedidoController(CrearPedidoUseCase useCase) {
        this.useCase = useCase;
    }

    @PostMapping
    public ResponseEntity<Void> crearPedido(@RequestBody PedidoRequest request) {
        useCase.ejecutar(request.producto(), request.cantidad());
        return ResponseEntity.status(HttpStatus.CREATED).build();
    }
}

Y ya lo tendríamos.

Cómo habíamos dicho la gracia de esto es:

• El dominio no sabe NADA de Spring.

• Puedes cambiar la base de datos, y el núcleo ni se entera.

• Puedes lanzar el caso de uso desde un controlador REST, o desde una CLI, o desde una cola de Kafka.

¡Solo tienes que enchufar otro adaptador!

Y qué ventajas nos da aplicar esta arquitectura:

✅ Alta testabilidad (puedes testear el dominio sin Spring ni BBDD)

✅ Flexibilidad para cambiar tecnologías

✅ Mantenimiento limpio

✅ Dominio desacoplado de todo lo externo

P.D: Tengo un proyecto montado en GitHub con una arquitectura hexagonal, si quieres que te lo envíe y te dé acceso, respóndeme a este correo y te lo envío.

Y nada espero que te haya gustado el correo y que te ayude para tu próximo proyecto, o por lo menos para tu próxima entrevista.

Nos leemos dentro de una semana.

Un saludo,