theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-quarkus/SKILL.md

@@ -0,0 +1,729 @@
+---
+name: patrones-quarkus
+description: Patrones de arquitectura para Quarkus 3.x LTS con Camel para mensajería, diseño de APIs REST, servicios CDI, acceso a datos con Panache y procesamiento asíncrono. Úsala para backends Java con Quarkus y arquitecturas orientadas a eventos.
+---
+
+# Patrones de desarrollo con Quarkus
+
+Patrones de arquitectura y APIs para servicios cloud-native y orientados a eventos con Quarkus 3.x y Apache Camel.
+
+## Cuándo usarla
+
+- Al construir APIs REST con JAX-RS o RESTEasy Reactive
+- Al estructurar capas resource → service → repository
+- Al implementar patrones orientados a eventos con Apache Camel y RabbitMQ
+- Al configurar Hibernate Panache, caché o streams reactivos
+- Al añadir validación, mapeo de excepciones o paginación
+- Al configurar perfiles para entornos dev/staging/producción (configuración YAML)
+- Al implementar logging personalizado con LogContext y Logback/encoder de Logstash
+- Al trabajar con CompletableFuture para operaciones asíncronas
+- Al implementar procesamiento con flujos condicionales
+- Al trabajar con compilación nativa GraalVM
+
+## Capa de servicio con múltiples dependencias
+
+```java
+@Slf4j
+@ApplicationScoped
+@RequiredArgsConstructor
+public class OrderProcessingService {
+
+    private final OrderValidator orderValidator;
+    private final EventService eventService;
+    private final OrderRepository orderRepository;
+    private final FulfillmentPublisher fulfillmentPublisher;
+    private final AuditPublisher auditPublisher;
+
+    @Transactional
+    public OrderReceipt process(CreateOrderCommand command) {
+        ValidationResult validation = orderValidator.validate(command);
+        if (!validation.valid()) {
+            eventService.createErrorEvent(command, "ORDER_REJECTED", validation.message());
+            throw new WebApplicationException(validation.message(), Response.Status.BAD_REQUEST);
+        }
+
+        Order order = Order.from(command);
+        orderRepository.persist(order);
+
+        OrderReceipt receipt = OrderReceipt.from(order);
+        fulfillmentPublisher.publishAsync(receipt);
+        auditPublisher.publish("ORDER_ACCEPTED", receipt);
+        eventService.createSuccessEvent(receipt, "ORDER_ACCEPTED");
+
+        log.info("Orden procesada {}", order.id);
+        return receipt;
+    }
+}
+```
+
+**Patrones clave:**
+- `@RequiredArgsConstructor` para inyección por constructor vía Lombok
+- `@Slf4j` para logging con Logback
+- `@Transactional` en métodos de servicio que escriben mediante Panache o repositorios
+- Validar la entrada antes de persistir o publicar mensajes
+- Registro de eventos para escenarios de éxito/error
+- Publicación asíncrona de mensajes con Camel
+
+## Patrón de contexto de logging personalizado (Logback)
+
+```java
+@ApplicationScoped
+public class ProcessingService {
+
+    public void processDocument(Document doc) {
+        LogContext logContext = CustomLog.getCurrentContext();
+        try (SafeAutoCloseable ignored = CustomLog.startScope(logContext)) {
+            // Añade contexto a todas las sentencias de log
+            logContext.put("documentId", doc.getId().toString());
+            logContext.put("documentType", doc.getType());
+            logContext.put("userId", SecurityContext.getUserId());
+
+            log.info("Iniciando procesamiento del documento");
+
+            // Todos los logs dentro de este scope heredan el contexto
+            processInternal(doc);
+
+            log.info("Procesamiento del documento completado");
+        } catch (Exception e) {
+            log.error("Falló el procesamiento del documento", e);
+            throw e;
+        }
+    }
+}
+```
+
+**Configuración de Logback (logback.xml):**
+
+```xml
+<configuration>
+    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
+            <includeContext>true</includeContext>
+            <includeMdc>true</includeMdc>
+        </encoder>
+    </appender>
+
+    <logger name="com.example" level="INFO"/>
+    <root level="WARN">
+        <appender-ref ref="CONSOLE"/>
+    </root>
+</configuration>
+```
+
+## Patrón de servicio de eventos
+
+```java
+@Slf4j
+@ApplicationScoped
+@RequiredArgsConstructor
+public class EventService {
+    private final EventRepository eventRepository;
+    private final ObjectMapper objectMapper;
+
+    public void createSuccessEvent(Object payload, String eventType) {
+        Objects.requireNonNull(payload, "El payload no puede ser nulo");
+        Event event = new Event();
+        event.setType(eventType);
+        event.setStatus(EventStatus.SUCCESS);
+        event.setPayload(serializePayload(payload));
+        event.setTimestamp(Instant.now());
+
+        eventRepository.persist(event);
+        log.info("Evento de éxito creado: {}", eventType);
+    }
+
+    public void createErrorEvent(Object payload, String eventType, String errorMessage) {
+        Objects.requireNonNull(payload, "El payload no puede ser nulo");
+        if (errorMessage == null || errorMessage.isBlank()) {
+            throw new IllegalArgumentException("El mensaje de error no puede estar en blanco");
+        }
+        Event event = new Event();
+        event.setType(eventType);
+        event.setStatus(EventStatus.ERROR);
+        event.setErrorMessage(errorMessage);
+        event.setPayload(serializePayload(payload));
+        event.setTimestamp(Instant.now());
+
+        eventRepository.persist(event);
+        log.error("Evento de error creado: {} - {}", eventType, errorMessage);
+    }
+
+    private String serializePayload(Object payload) {
+        try {
+            return objectMapper.writeValueAsString(payload);
+        } catch (JsonProcessingException e) {
+            throw new IllegalStateException("No se pudo serializar el payload del evento", e);
+        }
+    }
+}
+```
+
+## Publicación de mensajes con Camel (RabbitMQ)
+
+```java
+@Slf4j
+@ApplicationScoped
+@RequiredArgsConstructor
+public class BusinessRulesPublisher {
+    private final ProducerTemplate producerTemplate;
+
+    public void publishSync(BusinessRulesPayload payload) {
+        producerTemplate.sendBody(
+            "direct:business-rules-publisher",
+            payload
+        );
+    }
+}
+```
+
+**Configuración de la ruta Camel:**
+
+```java
+@ApplicationScoped
+public class BusinessRulesRoute extends RouteBuilder {
+
+    @ConfigProperty(name = "camel.rabbitmq.queue.business-rules")
+    String businessRulesQueue;
+
+    @ConfigProperty(name = "rabbitmq.host")
+    String rabbitHost;
+
+    @ConfigProperty(name = "rabbitmq.port")
+    Integer rabbitPort;
+
+    @Override
+    public void configure() {
+        from("direct:business-rules-publisher")
+            .routeId("business-rules-publisher")
+            .log("Publicando mensaje en RabbitMQ: ${body}")
+            .marshal().json(JsonLibrary.Jackson)
+            .toF("spring-rabbitmq:%s?hostname=%s&portNumber=%d",
+                businessRulesQueue, rabbitHost, rabbitPort);
+    }
+}
+```
+
+## Rutas directas de Camel (en memoria)
+
+```java
+@ApplicationScoped
+public class DocumentProcessingRoute extends RouteBuilder {
+
+    @Override
+    public void configure() {
+        // Manejo de errores
+        onException(ValidationException.class)
+            .handled(true)
+            .to("direct:validation-error-handler")
+            .log("Error de validación: ${exception.message}");
+
+        // Ruta principal de procesamiento
+        from("direct:process-document")
+            .routeId("document-processing")
+            .log("Procesando documento: ${header.documentId}")
+            .bean(DocumentValidator.class, "validate")
+            .bean(DocumentTransformer.class, "transform")
+            .choice()
+                .when(header("documentType").isEqualTo("INVOICE"))
+                    .to("direct:process-invoice")
+                .when(header("documentType").isEqualTo("CREDIT_NOTE"))
+                    .to("direct:process-credit-note")
+                .otherwise()
+                    .to("direct:process-generic")
+            .end();
+
+        from("direct:validation-error-handler")
+            .bean(EventService.class, "createErrorEvent")
+            .log("Error de validación gestionado");
+    }
+}
+```
+
+## Procesamiento de archivos con Camel
+
+```java
+@ApplicationScoped
+public class FileMonitoringRoute extends RouteBuilder {
+
+    @ConfigProperty(name = "file.input.directory")
+    String inputDirectory;
+
+    @ConfigProperty(name = "file.processed.directory")
+    String processedDirectory;
+
+    @ConfigProperty(name = "file.error.directory")
+    String errorDirectory;
+
+    @Override
+    public void configure() {
+        from("file:" + inputDirectory + "?move=" + processedDirectory +
+             "&moveFailed=" + errorDirectory + "&delay=5000")
+            .routeId("file-monitor")
+            .log("Procesando archivo: ${header.CamelFileName}")
+            .to("direct:process-file");
+
+        from("direct:process-file")
+            .bean(OrderProcessingService.class, "processFile")
+            .log("Procesamiento del archivo completado");
+    }
+}
+```
+
+## Invocación de beans desde Camel
+
+```java
+@ApplicationScoped
+public class InvoiceRoute extends RouteBuilder {
+
+    @Override
+    public void configure() {
+        from("direct:invoice-validation")
+            .bean(InvoiceFlowValidator.class, "validateFlowWithConfig")
+            .log("Resultado de validación: ${body}");
+
+        from("direct:persist-and-publish")
+            .bean(DocumentJobService.class, "createDocumentAndJobEntities")
+            .bean(BusinessRulesPublisher.class, "publishAsync")
+            .bean(EventService.class, "createSuccessEvent(${body}, 'PUBLISHED')");
+    }
+}
+```
+
+## Estructura de la API REST
+
+```java
+@Path("/api/documents")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+@RequiredArgsConstructor
+public class DocumentResource {
+  private final DocumentService documentService;
+
+  @GET
+  public Response list(
+      @QueryParam("page") @DefaultValue("0") int page,
+      @QueryParam("size") @DefaultValue("20") int size) {
+    List<Document> documents = documentService.list(page, size);
+    return Response.ok(documents).build();
+  }
+
+  @POST
+  public Response create(@Valid CreateDocumentRequest request, @Context UriInfo uriInfo) {
+    Document document = documentService.create(request);
+    URI location = uriInfo.getAbsolutePathBuilder()
+        .path(String.valueOf(document.id))
+        .build();
+    return Response.created(location).entity(DocumentResponse.from(document)).build();
+  }
+
+  @GET
+  @Path("/{id}")
+  public Response getById(@PathParam("id") Long id) {
+    return documentService.findById(id)
+        .map(DocumentResponse::from)
+        .map(Response::ok)
+        .orElse(Response.status(Response.Status.NOT_FOUND))
+        .build();
+  }
+}
+```
+
+## Patrón de repositorio (Panache Repository)
+
+```java
+@ApplicationScoped
+public class DocumentRepository implements PanacheRepository<Document> {
+
+  public List<Document> findByStatus(DocumentStatus status, int page, int size) {
+    return find("status = ?1 order by createdAt desc", status)
+        .page(page, size)
+        .list();
+  }
+
+  public Optional<Document> findByReferenceNumber(String referenceNumber) {
+    return find("referenceNumber", referenceNumber).firstResultOptional();
+  }
+
+  public long countByStatusAndDate(DocumentStatus status, LocalDate date) {
+    return count("status = ?1 and createdAt >= ?2", status, date.atStartOfDay());
+  }
+}
+```
+
+## Capa de servicio con transacciones
+
+```java
+@ApplicationScoped
+@RequiredArgsConstructor
+public class DocumentService {
+  private final DocumentRepository repo;
+  private final EventService eventService;
+
+  @Transactional
+  public Document create(CreateDocumentRequest request) {
+    Document document = new Document();
+    document.setReferenceNumber(request.referenceNumber());
+    document.setDescription(request.description());
+    document.setStatus(DocumentStatus.PENDING);
+    document.setCreatedAt(Instant.now());
+
+    repo.persist(document);
+
+    eventService.createSuccessEvent(document, "DOCUMENT_CREATED");
+
+    return document;
+  }
+
+  public Optional<Document> findById(Long id) {
+    return repo.findByIdOptional(id);
+  }
+
+  public List<Document> list(int page, int size) {
+    return repo.findAll()
+        .page(page, size)
+        .list();
+  }
+}
+```
+
+## DTOs y validación
+
+```java
+public record CreateDocumentRequest(
+    @NotBlank @Size(max = 200) String referenceNumber,
+    @NotBlank @Size(max = 2000) String description,
+    @NotNull @FutureOrPresent Instant validUntil,
+    @NotEmpty List<@NotBlank String> categories) {}
+
+public record DocumentResponse(Long id, String referenceNumber, DocumentStatus status) {
+  public static DocumentResponse from(Document document) {
+    return new DocumentResponse(document.getId(), document.getReferenceNumber(),
+        document.getStatus());
+  }
+}
+```
+
+## Mapeo de excepciones
+
+```java
+@Provider
+public class ValidationExceptionMapper implements ExceptionMapper<ConstraintViolationException> {
+  @Override
+  public Response toResponse(ConstraintViolationException exception) {
+    String message = exception.getConstraintViolations().stream()
+        .map(cv -> cv.getPropertyPath() + ": " + cv.getMessage())
+        .collect(Collectors.joining(", "));
+
+    return Response.status(Response.Status.BAD_REQUEST)
+        .entity(Map.of("error", "validation_error", "message", message))
+        .build();
+  }
+}
+
+@Provider
+@Slf4j
+public class GenericExceptionMapper implements ExceptionMapper<Exception> {
+
+  @Override
+  public Response toResponse(Exception exception) {
+    log.error("Excepción no gestionada", exception);
+    return Response.status(Response.Status.INTERNAL_SERVER_ERROR)
+        .entity(Map.of("error", "internal_error", "message", "Ocurrió un error inesperado"))
+        .build();
+  }
+}
+```
+
+## Operaciones asíncronas con CompletableFuture
+
+```java
+@Slf4j
+@ApplicationScoped
+@RequiredArgsConstructor
+public class FileStorageService {
+    private final S3Client s3Client;
+    private final ExecutorService executorService;
+
+    @ConfigProperty(name = "storage.bucket-name")
+    String bucketName;
+
+    public CompletableFuture<StoredDocumentInfo> uploadOriginalFile(
+            InputStream inputStream,
+            long size,
+            LogContext logContext,
+            InvoiceFormat format) {
+
+        return CompletableFuture.supplyAsync(() -> {
+            try (SafeAutoCloseable ignored = CustomLog.startScope(logContext)) {
+                String path = generateStoragePath(format);
+
+                PutObjectRequest request = PutObjectRequest.builder()
+                    .bucket(bucketName)
+                    .key(path)
+                    .contentLength(size)
+                    .build();
+
+                s3Client.putObject(request, RequestBody.fromInputStream(inputStream, size));
+
+                log.info("Archivo subido a S3: {}", path);
+
+                return new StoredDocumentInfo(path, size, Instant.now());
+            } catch (Exception e) {
+                log.error("No se pudo subir el archivo a S3", e);
+                throw new StorageException("Falló la subida", e);
+            }
+        }, executorService);
+    }
+}
+```
+
+## Caché
+
+```java
+@ApplicationScoped
+@RequiredArgsConstructor
+public class DocumentCacheService {
+  private final DocumentRepository repo;
+
+  @CacheResult(cacheName = "document-cache")
+  public Optional<Document> getById(@CacheKey Long id) {
+    return repo.findByIdOptional(id);
+  }
+
+  @CacheInvalidate(cacheName = "document-cache")
+  public void evict(@CacheKey Long id) {}
+
+  @CacheInvalidateAll(cacheName = "document-cache")
+  public void evictAll() {}
+}
+```
+
+## Configuración en YAML
+
+```yaml
+# application.yml
+"%dev":
+  quarkus:
+    datasource:
+      jdbc:
+        url: jdbc:postgresql://localhost:5432/dev_db
+      username: dev_user
+      password: ${DB_PASSWORD}
+    hibernate-orm:
+      database:
+        generation: drop-and-create
+
+  rabbitmq:
+    host: localhost
+    port: 5672
+    username: ${RABBITMQ_USER}
+    password: ${RABBITMQ_PASSWORD}
+
+"%test":
+  quarkus:
+    datasource:
+      jdbc:
+        url: jdbc:h2:mem:test
+    hibernate-orm:
+      database:
+        generation: drop-and-create
+
+"%prod":
+  quarkus:
+    datasource:
+      jdbc:
+        url: ${DATABASE_URL}
+      username: ${DB_USER}
+      password: ${DB_PASSWORD}
+    hibernate-orm:
+      database:
+        generation: validate
+
+  rabbitmq:
+    host: ${RABBITMQ_HOST}
+    port: ${RABBITMQ_PORT}
+    username: ${RABBITMQ_USER}
+    password: ${RABBITMQ_PASSWORD}
+
+# Configuración de Camel
+camel:
+  rabbitmq:
+    queue:
+      business-rules: business-rules-queue
+      invoice-processing: invoice-processing-queue
+```
+
+## Health checks
+
+```java
+@Readiness
+@ApplicationScoped
+@RequiredArgsConstructor
+public class DatabaseHealthCheck implements HealthCheck {
+  private final AgroalDataSource dataSource;
+
+  @Override
+  public HealthCheckResponse call() {
+    try (Connection conn = dataSource.getConnection()) {
+      boolean valid = conn.isValid(2);
+      return HealthCheckResponse.named("Database connection")
+          .status(valid)
+          .build();
+    } catch (SQLException e) {
+      return HealthCheckResponse.down("Database connection");
+    }
+  }
+}
+
+@Liveness
+@ApplicationScoped
+public class CamelHealthCheck implements HealthCheck {
+  @Inject
+  CamelContext camelContext;
+
+  @Override
+  public HealthCheckResponse call() {
+    boolean isStarted = camelContext.getStatus().isStarted();
+    return HealthCheckResponse.named("Camel Context")
+        .status(isStarted)
+        .build();
+  }
+}
+```
+
+## Dependencias (Maven)
+
+```xml
+<properties>
+    <quarkus.platform.version>3.27.0</quarkus.platform.version>
+    <lombok.version>1.18.42</lombok.version>
+    <assertj-core.version>3.24.2</assertj-core.version>
+    <jacoco-maven-plugin.version>0.8.13</jacoco-maven-plugin.version>
+    <maven.compiler.release>17</maven.compiler.release>
+</properties>
+
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>io.quarkus.platform</groupId>
+            <artifactId>quarkus-bom</artifactId>
+            <version>${quarkus.platform.version}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus.platform</groupId>
+            <artifactId>quarkus-camel-bom</artifactId>
+            <version>${quarkus.platform.version}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+
+<dependencies>
+    <!-- Núcleo de Quarkus -->
+    <dependency>
+        <groupId>io.quarkus</groupId>
+        <artifactId>quarkus-arc</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>io.quarkus</groupId>
+        <artifactId>quarkus-config-yaml</artifactId>
+    </dependency>
+
+    <!-- Extensiones de Camel -->
+    <dependency>
+        <groupId>org.apache.camel.quarkus</groupId>
+        <artifactId>camel-quarkus-spring-rabbitmq</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>org.apache.camel.quarkus</groupId>
+        <artifactId>camel-quarkus-direct</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>org.apache.camel.quarkus</groupId>
+        <artifactId>camel-quarkus-bean</artifactId>
+    </dependency>
+
+    <!-- Lombok -->
+    <dependency>
+        <groupId>org.projectlombok</groupId>
+        <artifactId>lombok</artifactId>
+        <version>${lombok.version}</version>
+        <scope>provided</scope>
+    </dependency>
+
+    <!-- Logging -->
+    <dependency>
+        <groupId>io.quarkiverse.logging.logback</groupId>
+        <artifactId>quarkus-logging-logback</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>net.logstash.logback</groupId>
+        <artifactId>logstash-logback-encoder</artifactId>
+    </dependency>
+</dependencies>
+```
+
+## Buenas prácticas
+
+### Arquitectura
+- Usa `@RequiredArgsConstructor` con Lombok para inyección por constructor
+- Mantén la capa de servicio delgada; delega la lógica compleja a clases especializadas
+- Usa rutas de Camel para enrutamiento de mensajes y patrones de integración
+- Prefiere el patrón Panache Repository para el acceso a datos
+
+### Orientado a eventos
+- Registra siempre las operaciones con EventService (eventos de éxito/error)
+- Usa endpoints `direct:` de Camel para enrutamiento en memoria
+- Usa el componente `spring-rabbitmq` para la integración con RabbitMQ
+- Implementa publicación asíncrona con `ProducerTemplate.asyncSendBody()`
+
+### Logging
+- Usa Logback con el encoder de Logstash para logging estructurado
+- Propaga el LogContext a través de las llamadas de servicio con `SafeAutoCloseable`
+- Añade información contextual al LogContext para el trazado de peticiones
+- Usa `@Slf4j` en lugar de instanciar loggers manualmente
+
+### Operaciones asíncronas
+- Usa CompletableFuture para operaciones de E/S no bloqueantes
+- Llama a `.join()` cuando necesites esperar la finalización
+- Maneja correctamente las excepciones de CompletableFuture
+- Pasa el LogContext a las operaciones asíncronas para el trazado
+
+### Configuración
+- Usa configuración YAML (`quarkus-config-yaml`)
+- Configuración por perfiles para entornos dev/test/prod
+- Externaliza la configuración sensible a variables de entorno
+- Usa `@ConfigProperty` para inyección de configuración con tipos seguros
+
+### Validación
+- Valida en la capa resource con `@Valid`
+- Usa anotaciones de Bean Validation en los DTOs
+- Mapea excepciones a respuestas HTTP adecuadas con `@Provider`
+
+### Transacciones
+- Usa `@Transactional` en métodos de servicio que modifican datos
+- Mantén las transacciones cortas y enfocadas
+- Evita llamar a operaciones asíncronas dentro de transacciones
+
+### Testing
+- Usa `camel-quarkus-junit5` para probar rutas
+- Usa AssertJ para las aserciones
+- Mockea todas las dependencias externas
+- Prueba a fondo la lógica de flujos condicionales
+
+### Específico de Quarkus
+- Mantente en la última versión LTS (3.x)
+- Usa el modo dev de Quarkus para hot reload
+- Añade health checks para preparación de producción
+- Prueba periódicamente la compatibilidad con compilación nativa
+
+## Skills relacionadas
+
+- `seguridad-quarkus`
+- `tdd-quarkus`
+- `verificacion-quarkus`
+- `estandares-java`
+- `patrones-jpa`