Padrões de Desenvolvimento Quarkus

Arquitetura e padrões de API do Quarkus 3.x para serviços nativos da nuvem e orientados a eventos com Apache Camel.

Quando Ativar

• Construindo APIs REST com JAX-RS ou RESTEasy Reactive
• Estruturando camadas de recurso → serviço → repositório
• Implementando padrões orientados a eventos com Apache Camel e RabbitMQ
• Configurando Hibernate Panache, cache ou fluxos reativos
• Adicionando validação, mapeamento de exceções ou paginação
• Configurando perfis para ambientes de desenvolvimento/staging/produção (configuração YAML)
• Log personalizado com LogContext e codificador Logback/Logstash
• Trabalhando com CompletableFuture para operações assíncronas
• Implementando processamento de fluxo condicional
• Trabalhando com compilação nativa GraalVM

Camada de Serviço com Múltiplas Dependências

@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("Processed order {}", order.id);
        return receipt;
    }
}

Padrões Chave:

• @RequiredArgsConstructor para injeção de construtor via Lombok
• @Slf4j para logging com Logback
• @Transactional em métodos de serviço que escrevem através do Panache ou repositórios
• Valide a entrada antes da persistência ou publicação de mensagens
• Rastreamento de eventos para cenários de sucesso/erro
• Publicação assíncrona de mensagens Camel

Padrão de Contexto de Log Personalizado (Logback)

@ApplicationScoped
public class ProcessingService {

    public void processDocument(Document doc) {
        LogContext logContext = CustomLog.getCurrentContext();
        try (SafeAutoCloseable ignored = CustomLog.startScope(logContext)) {
            // Add context to all log statements
            logContext.put("documentId", doc.getId().toString());
            logContext.put("documentType", doc.getType());
            logContext.put("userId", SecurityContext.getUserId());

            log.info("Starting document processing");

            // All logs within this scope inherit the context
            processInternal(doc);

            log.info("Document processing completed");
        } catch (Exception e) {
            log.error("Document processing failed", e);
            throw e;
        }
    }
}

Configuração do Logback (logback.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>

Padrão de Serviço de Eventos

@Slf4j
@ApplicationScoped
@RequiredArgsConstructor
public class EventService {
    private final EventRepository eventRepository;
    private final ObjectMapper objectMapper;

    public void createSuccessEvent(Object payload, String eventType) {
        Objects.requireNonNull(payload, "Payload cannot be null");
        Event event = new Event();
        event.setType(eventType);
        event.setStatus(EventStatus.SUCCESS);
        event.setPayload(serializePayload(payload));
        event.setTimestamp(Instant.now());

        eventRepository.persist(event);
        log.info("Success event created: {}", eventType);
    }

    public void createErrorEvent(Object payload, String eventType, String errorMessage) {
        Objects.requireNonNull(payload, "Payload cannot be null");
        if (errorMessage == null || errorMessage.isBlank()) {

…