Spring Boot Async Ultimate Template 🚀

Índice

1. Descripción General
2. Características Principales
3. Tecnologías y Dependencias
4. Instalación y Puesta en Marcha
5. Arquitectura del proyecto
6. Test de integración
7. Interfaces disponibles
8. Aplicación de línea de comando

Descripción General 🌟

Plantilla avanzada de Spring Boot orientada a la creación de microservicios modernos, escalables y mantenibles. Implementa arquitectura hexagonal, comunicación basada en eventos con Kafka y Avro, y está pensada para facilitar la integración en entornos reales con herramientas como PostgreSQL, Docker Compose y pruebas asíncronas.

Además, incluye una aplicación de línea de comandos para incorporar fácilmente las configuraciones esenciales a proyectos existentes.

Características Principales

• Arquitectura Hexagonal
• Kafka preconfigurado para producir y consumir eventos
• Serialización con Avro y validación vía Confluent Schema Registry
• Documentación automática con AsyncAPI/Swagger
• Containerización lista con Docker Compose
• Pruebas de integración asíncronas con Awaitility y JUnit 5
• PostgreSQL con soporte vectorial (PGVector)
• Aplicación CLI para facilitar configuración de nuevos proyectos
• Actuator para monitorización

Tecnologías & Dependenciass️

• Java 21
• Spring Boot 3.4.5
• Spring Web + Spring Data JPA
• Kafka + Spring Kafka
• Avro + Confluent Schema Registry
• PostgreSQL
• MapStruct + Lombok
• Awaitility + JUnit 5
• AsyncAPI / Swagger para documentación
• Docker & Docker Compose

Instalación & Puesta en Marcha

1. Clona el repositorio:

   git clone https://github.com/David-DAM/spring-boot-async-template-ultimate.git
   cd spring-boot-async-template-ultimate

2. Configura las variables de entorno si es necesario.
3. Instala las dependencias

   mvn clean install

4. Inicia los servicios:

   docker-compose up -d

5. Ejecuta la aplicación:

   ./mvn spring-boot:run

Arquitectura del proyecto

Este proyecto aplica arquitectura hexagonal junto con patrones como Mediator y Strategy, promoviendo una separación clara de responsabilidades y una alta extensibilidad para entornos basados en eventos.

Flujo de eventos con Kafka

Los eventos entrantes se consumen mediante un único Kafka Listener centralizado. Este listener delega dinámicamente la ejecución al consumidor específico utilizando un patrón Strategy, donde la clave de decisión es el schema type del evento (generado automáticamente a partir de los archivos Avro).

Una vez delegado, el consumidor transforma el evento y lo lleva a la capa de aplicación, donde se ejecuta la lógica de negocio a través del patrón Mediator.

Al finalizar el procesamiento, se pueden generar nuevos eventos de salida, como por ejemplo los eventos de tipo user.validation, que son enviados de vuelta a Kafka a través de un publisher especializado.

Estructura de operación (Command pattern con Mediator)

Cada operación está compuesta por:

Command: Objeto que encapsula la entrada del usuario o evento.

Handler: Contiene la lógica de negocio asociada al Command.

Una capa personalizada de mediación enruta cada Command hacia su Handler correspondiente de manera desacoplada, permitiendo controladores y consumidores delgados y de propósito único.

Tests de integración

Dado que esta aplicación está orientada a eventos y flujos asíncronos, los tests están especialmente diseñados para garantizar consistencia y confiabilidad bajo ese enfoque.

Asincronía controlada con Awaitility

Se utiliza la librería Awaitility para esperar condiciones específicas en los tests, como la persistencia de datos en base de datos o la recepción de eventos de Kafka. Esto evita race conditions y errores intermitentes.

Además, se han creado métodos auxiliares reutilizables para facilitar:

• Esperar a que una entidad específica esté disponible en la base de datos.
• Confirmar que ciertos eventos hayan sido publicados o procesados.
• Validar estados de forma tolerante al tiempo.

Limpieza de entorno

Cada clase de tests limpia sus recursos para evitar efectos colaterales:

• Se eliminan los mensajes de los topics de Kafka después de cada método para asegurar un entorno limpio.
• Se utiliza @Sql para preparar y limpiar el estado de la base de datos antes y después de cada test, como en el ejemplo:

@Sql(scripts = "/it/user/delete/data.sql", executionPhase = BEFORE_TEST_METHOD)
@Sql(scripts = "/it/data-cleanup.sql", executionPhase = AFTER_TEST_METHOD)

Interfaces disponibles

• Kafka Control Center (monitorización de Kafka): http://localhost:9021
• Schema Registry (gestión de esquemas Avro): http://localhost:8081
• PostgreSQL (base de datos): disponible en localhost:5432 (usuario: root, contraseña: password)

Como usar la aplicación de línea de comandos

1. Tener instalado una versión de Java igual o superior a la 17

2. Ir a la sección de RELEASES para descargar la última versión disponible de la aplicación

3. Tras haber descargado él .jar con la aplicación moverlo a la raiz del proyecto

4. Usando el siguiente comando para ejecutar la aplicación

   java -jar cli.jar

5. Una vez iniciada la aplicación podrás escribir el comando help para ver una lista de los comandos existentes

6. Con ellos podrás preconfigurar tu base de datos, cache, seguridad, utilidades, etc...