Organizar un proyecto Spring Boot por capas orientadas al dominio te ayuda a separar responsabilidades, mantener el código legible y escalar tu API sin dolores de cabeza. Esta guía muestra cómo estructurar paquetes de dominio, web y persistence para que tu aplicación crezca con orden desde el primer día.

Por qué usar una arquitectura por capas orientada al dominio

La idea central es que el core de tu aplicación viva en el dominio, y el resto de capas giren alrededor de él. Así, cuando un módulo cambie, no arrastras toda la aplicación contigo.

Esta separación te da tres beneficios concretos:

• Responsabilidades claras entre lo que es lógica de negocio, lo que expone endpoints y lo que habla con la base de datos.
• Código más legible porque cada paquete tiene un propósito único.
• Escalabilidad real cuando la aplicación crece y necesitas agregar nuevas funcionalidades sin romper lo existente.

¿Qué es una arquitectura orientada al dominio? Es un enfoque donde el dominio (la lógica de negocio) ocupa el centro de la aplicación, y las capas externas como web o persistencia dependen de él, no al revés.

Cómo crear los paquetes base de dominio, web y persistence

Dentro de com.platzi.play necesitas tres paquetes hermanos que reflejan las capas de tu aplicación. Cada uno cumple una misión distinta y debe mantenerse aislado del resto.

Qué va en el paquete domain

El paquete domain aloja el core de la aplicación. Aquí viven las reglas de negocio y los servicios que orquestan esa lógica.

Dentro de domain se crea un subpaquete domain.service donde se mueve la interfaz PlatziPlayAIService. Al arrastrar la clase, IntelliJ actualiza automáticamente los nombres de paquetes y los imports, así que la aplicación sigue funcionando sin tocar código a mano [1:30].

Qué va en el paquete web

El paquete web agrupa todo lo que expone la aplicación al exterior. Como puede contener varias responsabilidades, se crea un subpaquete web.controller para los controladores.

La clase HelloController se mueve a com.platzi.play.web.controller. En el mismo paso, se ajusta el mapping para que el saludo responda en /hello en lugar de la raíz / [1:50].

Qué va en el paquete persistence

El paquete persistence se reserva para toda la comunicación con la base de datos. Por ahora queda vacío, pero es el lugar donde se conectará Postgres en la siguiente clase.

¿Para qué sirve separar persistence del dominio? Para que el dominio no dependa de cómo se guardan los datos. Puedes cambiar de base de datos sin tocar la lógica de negocio.

Dónde dejar la clase principal de Spring Boot

La clase PlatziPlay, encargada de arrancar la aplicación, se queda en la raíz del paquete com.platzi.play. No pertenece a ninguna capa específica porque su rol es ejecutar el proyecto completo.

Al relanzar la aplicación después de reorganizar, la URL raíz deja de responder y el saludo aparece en /hello. Esa pequeña validación confirma que la nueva estructura funciona y que los controladores siguen activos [2:40].

Existe una arquitectura perfecta para todos los proyectos

No. Ninguna arquitectura es la bala de plata que resuelve todos los casos. El contexto del producto, las necesidades del equipo y la infraestructura definen qué patrón conviene en cada momento.

Algunos factores que cambian la decisión:

• El tamaño del equipo y su experiencia.
• La complejidad del dominio de negocio.
• Los requisitos de escalabilidad y despliegue.

Por eso conviene profundizar en fundamentos de arquitectura antes de casarte con un único enfoque. La estructura por capas orientada al dominio es un excelente punto de partida para APIs con Spring Boot, pero no es la única opción válida.

Qué sigue después de estructurar el proyecto

Con la base lista, el siguiente paso es conectar la aplicación a una base de datos real. Vas a usar Docker para levantar una instancia de Postgres y enlazarla con el paquete persistence que dejaste preparado.

¿Tu proyecto actual sigue una arquitectura por capas o usas otro enfoque? Cuéntame en los comentarios cómo organizas tus paquetes en Spring Boot.