Développement d'application Quarkus

Portée : code applicatif au sein d'un projet Quarkus existant. La création de projet est create-quarkus-project ; les Dev Services et tests sont quarkus-dev-services-and-testing ; les images natives et conteneurs sont quarkus-native-and-container ; la conception de mapping JPA et requêtes core peut utiliser la skill optionnelle java-hibernate-jpa si installée (sinon voir le guide Hibernate ORM, https://quarkus.io/guides/hibernate-orm, et la documentation Jakarta Persistence).

Règles de l'agent

1. Détection en premier : lire pom.xml/build.gradle pour quarkus.platform.version, la release Java, et les extensions déjà présentes. Conserver la version ; utiliser ce que le projet utilise déjà (par exemple quarkus-resteasy* reste s'il est présent).
2. Ajouter des extensions avec quarkus extension add <name> ou ./mvnw quarkus:add-extension -Dextensions=<name> ; ne jamais deviner les artifact ids ou versions à la main (le platform BOM les gère). Lister les candidats avec quarkus extension list --installable --search=<text>.
3. Demander à l'utilisateur avant d'ajouter Kafka, OIDC/Keycloak ou toute nouvelle dépendance infrastructure (ils lancent des conteneurs en dev/test et changent les besoins de déploiement).
4. Ne jamais utiliser les extensions de compatibilité Spring (quarkus-spring-*) sauf si le projet le fait déjà.
5. Vérifier en dev mode (./mvnw quarkus:dev, puis /q/dev-ui) et ./mvnw verify ; écrire un @QuarkusTest par feature. Ne pas affirmer que quelque chose fonctionne sans l'avoir exécuté.
6. Utiliser les imports jakarta.*, les records pour les DTOs, les ressources fines déléguant aux services.
7. Ne jamais coder en dur les secrets ou ajouter les credentials à application.properties ; voir references/config-cdi.md.

Décisions rapides

Pièges coûteux en temps

• Quarkus résout CDI à la compilation : un bean inutilisé peut être retiré. Les beans cherchés uniquement par programmation ont besoin de @Unremovable.
• Ne pas lire ou écrire les champs publics d'un bean normal-scoped (@ApplicationScoped) depuis un autre bean ou test : on atteint le client proxy, pas l'instance (vérifié : un champ compteur lu via le proxy retournait 0). Utiliser des méthodes.
• Ne pas bloquer sur la boucle d'événements (méthodes @NonBlocking, types de retour Uni/Multi s'exécutant sur les threads I/O). Retirer tout @NonBlocking existant de la méthode (le combiner avec @Blocking ou @RunOnVirtualThread fait échouer la compilation), puis ajouter @Blocking ou @RunOnVirtualThread (voir references/reactive-messaging.md).
• Les changements aux propriétés de compilation exigent une recompilation ; les propriétés runtime peuvent être surchargées par des variables d'env (QUARKUS_DATASOURCE_JDBC_URL).
• Ne pas configurer les URLs pour bases de données/brokers/Keycloak en %dev/%test : cela désactive les Dev Services.
• drop-and-create est pour dev/test seulement ; utiliser Flyway ou Liquibase pour la production.

Vérifié sur Quarkus 3.40.1 et 3.27.6 (cible Java 21, Maven) avec une app scaffoldée et mvn verify (15 tests : REST+validation+mapper, OpenAPI, config mapping, Panache sur Dev Services PostgreSQL, round trip Kafka Dev Service, tokens Keycloak Dev Service, health, metrics, fault tolerance, cache, scheduler). Recouper les noms par rapport à la version du projet.