Lee primero el README.md del proyecto y respeta todas las decisiones arquitectónicas documentadas ahí.
El proyecto ya tiene:
- estructura de paquetes definida
- clases creadas
- arquitectura establecida
- convenciones de organización acordadas
No rediseñes la arquitectura ni reestructures paquetes.
La implementación se realizará por iteraciones pequeñas. En esta iteración debes modificar únicamente las clases relacionadas con el alcance solicitado.
Mantén:
- código limpio y legible
- separación clara de responsabilidades
- bajo acoplamiento
- cohesión alta
- consistencia de naming
- simplicidad razonable
Aplica buenas prácticas en la medida adecuada para el tamaño del proyecto:
- SOLID cuando aplique naturalmente
- separación de responsabilidades
- métodos pequeños y claros
- nombres semánticos
- evitar lógica duplicada
- evitar complejidad innecesaria
No introduzcas patrones o capas adicionales que no existan actualmente en el proyecto.
La arquitectura definida es:
presentation
business
data
integration
common
presentation: exposición RESTbusiness: lógica y orquestaciónintegration: comunicación con APIs externasdata: DTOs, modelos y mapperscommon: configuración y componentes transversales
Respeta estrictamente esas responsabilidades.
Los controllers:
- no deben contener lógica de negocio
- no deben consumir APIs externas
- no deben construir respuestas complejas manualmente
Solo:
- reciben requests
- delegan al service
- retornan responses
Los services:
- orquestan el flujo
- coordinan integración
- generan metadata transaccional
- aplican lógica del caso de uso
Aquí sí puede existir:
- generación de UUID
- generación de fechas
- decisiones de éxito/error
- logging de negocio
La capa integration encapsula totalmente la comunicación con Swagger Petstore.
No exponer detalles HTTP fuera de esta capa.
Usar RestClient.
Los mappers:
- únicamente transforman objetos
- deben ser puros
- no deben contener lógica de negocio
No generar dentro de mappers:
- UUID
- fechas
- status
- llamadas externas
- decisiones de negocio
Usa naming consistente y semántico.
PetController
PetService
PetServiceImpl
PetstoreClient
PetMapper
PetRequestDto
PetResponseDto
Usar verbos claros:
getPetById
createPet
toPetResponseDto
toPetstorePetDto
Evitar:
- nombres ambiguos
- abreviaturas innecesarias
- sufijos genéricos como
processData
Usar nombres explícitos:
petResponse
externalPet
createdPetResponse
transactionId
Evitar:
obj
data
response1
tmp
Usar SLF4J/Lombok logging.
No usar System.out.println.
Los logs deben ser:
- útiles
- simples
- sin ruido excesivo
Usar:
- excepciones específicas
- GlobalExceptionHandler
- respuestas HTTP coherentes
Evitar:
- catch genéricos innecesarios
- silenciamiento de errores
- retornar null
Los tests deben:
- validar comportamiento
- no depender de internet
- usar mocks
- mantener claridad
Priorizar:
- legibilidad
- intención
- comportamiento esperado
No generar tests excesivamente complejos.
La intención del proyecto no es únicamente resolver endpoints REST, sino implementar una solución pequeña pero bien estructurada, mantenible y coherente arquitectónicamente.
Prioriza:
- claridad
- mantenibilidad
- separación de responsabilidades
- consistencia
- simplicidad profesional