feat: implementación de API de productos similares con Spring WebFlux - Iván Vázquez Pérez

[ibrahivan]

🚀 Solución implementada

Aplicación reactiva desarrollada con Spring Boot 3.3 que expone el endpoint:

GET /product/{productId}/similar

Disponible en el puerto 5000, conforme al contrato definido en similarProducts.yaml.

⚙️ Tecnología elegida

Spring WebFlux + WebClient

Se ha optado por una arquitectura reactiva y no bloqueante, en lugar del stack MVC clásico, para responder eficientemente a un escenario de alta concurrencia.

Motivos principales

• 🔄 Flujo de llamadas: el endpoint requiere una llamada para obtener los IDs de productos similares y una llamada adicional por cada detalle de producto.
• ⛔ Eficiencia: con MVC tradicional, cada llamada HTTP bloquea un hilo. Bajo la carga prevista de hasta 200 usuarios virtuales concurrentes, este enfoque podría agotar rápidamente el pool de hilos.
• ⚡ Escalabilidad: con WebFlux, WebClient y Netty, las operaciones de red son no bloqueantes, permitiendo que pocos hilos gestionen un volumen elevado de conexiones.
• 🔀 Orden y paralelismo: se utiliza el operador flatMapSequential para lanzar las consultas de detalle en paralelo y, a la vez, preservar el orden original de los IDs similares en la respuesta final.

🛡️ Resiliencia

• ⏱️ Timeouts: límite configurable de 2 segundos de espera de respuesta por cada petición HTTP individual al servicio externo. Los productos que superen ese límite se descartan automáticamente para garantizar la fluidez del servicio.
• 🚫 Tolerancia a fallos: los errores 404 y 5xx de productos individuales se ignoran de forma controlada, omitiendo esos productos silenciosamente sin interrumpir ni penalizar la respuesta global.
• 🔎 Dominio: si el producto principal solicitado no existe, se gestiona mediante una excepción de dominio (ProductNotFoundException) que se traduce automáticamente en una respuesta HTTP 404.
• ⚠️ Errores inesperados: cualquier excepción no controlada es capturada por un GlobalExceptionHandler, asegurando que la API devuelva siempre un HTTP 500 en formato JSON en lugar del HTML de error por defecto.

🐳 Docker

• Dockerfile multi-stage:
  • Etapa de compilación utilizando Maven.
  • Imagen final optimizada y ligera basada en JRE 21.
• Orquestación: integración completa mediante docker-compose.yml.

📚 Documentación

Se han añadido comentarios Javadoc en español a todas las clases y métodos públicos para facilitar la comprensión y el mantenimiento de la solución técnica.

📁 Estructura del proyecto

similarproducts/
├── Dockerfile                          # Multi-stage build (Maven → JRE 21), tests incluidos en el build
├── .dockerignore                       # Excluye target/, .git, etc. del contexto Docker
├── pom.xml                             # Spring Boot 3.3 + WebFlux + Actuator
└── src/
    ├── main/java/com/knowmad/similarproducts/
    │   ├── SimilarProductsApplication.java
    │   ├── controller/
    │   │   ├── SimilarProductsController   # GET /product/{id}/similar → 200 / 404
    │   │   └── GlobalExceptionHandler      # Manejo global de errores inesperados → 500 JSON
    │   ├── service/
    │   │   └── SimilarProductsService      # Orquestación: IDs → detalles en paralelo
    │   ├── client/
    │   │   └── ProductClient               # WebClient con timeouts configurables y logs
    │   └── model/
    │       ├── ProductDetail               # Record DTO (id, name, price, availability)
    │       └── ProductNotFoundException    # Excepción de dominio → HTTP 404
    └── test/java/com/knowmad/similarproducts/
        ├── controller/
        │   └── SimilarProductsControllerTest   # 4 tests con WebFluxTest + WebTestClient
        └── service/
            └── SimilarProductsServiceTest      # 5 tests con Mockito + StepVerifier