Desenvolvimento de Aplicações Quarkus

Escopo: código da aplicação dentro de um projeto Quarkus existente. A criação do projeto é create-quarkus-project; Dev Services e testes são quarkus-dev-services-and-testing; imagens nativas e de contêiner são quarkus-native-and-container; o mapeamento JPA principal e o design de consultas podem usar a habilidade opcional java-hibernate-jpa se instalada (caso contrário, consulte o guia Hibernate ORM, https://quarkus.io/guides/hibernate-orm, e a documentação Jakarta Persistence).

Regras do Agente

1. Detectar primeiro: ler pom.xml/build.gradle para quarkus.platform.version, a versão do Java e as extensões já presentes. Mantenha a versão; use o que o projeto já utiliza (por exemplo, quarkus-resteasy* permanece se presente).
2. Adicionar extensões com quarkus extension add <name> ou ./mvnw quarkus:add-extension -Dextensions=<name>; nunca adivinhe IDs de artefatos ou versões manualmente (a BOM da plataforma os gerencia). Liste candidatos com quarkus extension list --installable --search=<text>.
3. Perguntar ao usuário antes de adicionar Kafka, OIDC/Keycloak ou qualquer nova dependência de infraestrutura (eles iniciam contêineres em dev/test e alteram as necessidades de implantação).
4. Nunca usar as extensões de compatibilidade Spring (quarkus-spring-*) a menos que o projeto já o faça.
5. Verificar com o modo dev (./mvnw quarkus:dev, depois /q/dev-ui) e ./mvnw verify; escrever um @QuarkusTest por funcionalidade. Não afirme que algo funciona sem executá-lo.
6. Usar importações jakarta.*, records para DTOs, recursos finos delegando para serviços.
7. Nunca codificar segredos ou adicionar credenciais em application.properties; veja references/config-cdi.md.

Decisões Rápidas

Armadilhas que custam tempo

• Quarkus resolve CDI em tempo de compilação: um bean não utilizado pode ser removido. Beans procurados apenas programaticamente precisam de @Unremovable.
• Não leia ou escreva campos públicos de um bean de escopo normal (@ApplicationScoped) de outro bean ou teste: você atinge o proxy do cliente, não a instância (verificado: um campo contador lido através do proxy retornou 0). Use métodos.
• Não bloqueie no loop de eventos (métodos @NonBlocking, tipos de retorno Uni/Multi executando em threads de I/O). Remova qualquer @NonBlocking existente do método (combiná-lo com @Blocking ou @RunOnVirtualThread falha a compilação), então adicione @Blocking ou @RunOnVirtualThread (veja references/reactive-messaging.md).
• Alterações em propriedades de tempo de compilação exigem recompilação; propriedades de tempo de execução podem ser substituídas por variáveis de ambiente (QUARKUS_DATASOURCE_JDBC_URL).
• Não configure URLs para bancos de dados/brokers/Keycloak em %dev/%test: isso desabilita o Dev Services.
• O gerenciamento de schema drop-and-create é apenas para dev/test; use Flyway ou Liquibase para produção.

Verificado em Quarkus 3.40.1 e 3.27.6 (alvo Java 21, Maven) com um aplicativo scaffold e mvn verify (15 testes: REST+validação+mapper, OpenAPI, mapeamento de configuração, Panache em PostgreSQL Dev Services, Kafka Dev Service round trip, tokens Keycloak Dev Service, health, métricas, tolerância a falhas, cache, scheduler). Re-verifique os nomes em relação à versão do projeto.