La structure d'un projet (6) : la cuisine qu'on prépare la veille
Par Dorian Chávez · cofondateur et Chief Executive Officer de Hábil ·
La même API de commandes, de Spring Boot à Quarkus : ce qui change dans chaque paquet, démarrage et mémoire mesurés, et ce que ce chiffre ne vous dit pas.
La structure d'un projet · épisode 6 sur 7 · Quarkus
Scénario : les personnages et l'histoire sont inventés. Les données techniques et les citations ont leur source à la fin.
En 1 minute
- C'est le même restaurant que dans l'épisode 5 :
apiest le serveur,servicele cuisinier,repositoryle garde-manger. Ce qui change, c'est la cuisine : l'outil de chaque rôle. - L'idée centrale de Quarkus est de faire « at build-time what traditional frameworks do at runtime » [1]. La cuisine se prépare la veille, et c'est pour cela qu'elle ouvre vite.
- Mesuré sur le modèle, jusqu'à la première commande créée : Spring Boot, 2,2 s et 437 MiB ; Quarkus sur la JVM (la machine virtuelle qui exécute Java), 1,2 s et 270 MiB ; Quarkus compilé en natif (un exécutable qui n'a pas besoin de la JVM), 46 ms et 60 MiB.
- Ouvrir vite n'est pas cuisiner vite. Dans le banc d'essai du guide officiel, le natif sert ~59 % de requêtes par seconde de moins que la JVM [2]. On choisit le natif pour le démarrage et la mémoire, la mesure en main.
- Les flèches pointent toujours vers l'intérieur, et le même test d'architecture passe au rouge si quelqu'un les inverse. Il y a une erreur qu'aucun test du modèle ne voit : tu la trouves avec un
grep. - Pour lundi : cherche
extends PanacheEntitydans ton projet. Chaque résultat est une fiche d'archive qui fait aussi office de garde-manger.
Dans cet article
- Que s'est-il passé lundi à 9:12 ?
- Qu'est-ce qui change, et qu'est-ce qui ne change pas ?
- Que veut dire « la veille » ?
- Qu'est-ce qui change dans chaque paquet ?
- À quelle vitesse ouvre-t-elle ?
- Les flèches vont-elles toujours vers l'intérieur ?
- Quelles sont cinq erreurs fréquentes ?
- Exercice : peux-tu cacher la fiche dans le ticket ?
- À retenir
- Et ensuite ?
- Le modèle et le cours
- Que fait Hábil ?
- Références
Que s'est-il passé lundi à 9:12 ?
Iván a vu une API démarrer en 46 millisecondes et a voulu tout passer en natif. Lucía lui a posé deux questions.
Lundi, 9:05. Troisième étage.
La nouvelle API de commandes avait les dossiers habituels : api, facade, service. Iván a cherché le serveur et a trouvé PedidoResource. Il n'y avait pas de @RestController, pas de classe avec un main, et le garde-manger n'était pas là où il l'attendait : il vivait dans model/.
Il l'a construite et l'a démarrée. Le journal a dit :
pedidos 0.1.0 on JVM (powered by Quarkus 3.40.1.2) started in 1.540s.
Listening on: http://0.0.0.0:8080. Management interface listening on http://0.0.0.0:9000.Deux ports. Il a noté la question et a continué.
Lundi, 9:12.
Lucía est passée à son poste, son café à la main.
— Maintenant, lance-la comme ça.
Elle lui a donné une commande qui a mis plus d'une minute à se terminer. Elle a laissé un fichier de 78 MiB dans target/. Iván l'a exécuté, a envoyé une commande et la commande a été créée. Entre le lancement du processus et la première réponse, il s'est écoulé 46 millisecondes.
— Quarante-six ? Celle de Spring met deux secondes. Il faut tout passer à ça.
— Combien de temps a pris la compilation ?
— Une minute et quelques.
— Et combien de commandes par seconde elle sert ?
Iván ne le savait pas. Personne ne l'avait mesuré.
— Demain, on prend le petit-déjeuner au petit resto d'en face, a dit Lucía. Arrive tôt.
Mardi, 7:30. Le petit resto d'en face.
La cuisine n'était pas encore ouverte. La cuisinière avait déjà émincé l'oignon, fait les sauces et mis les haricots à cuire. À une heure, elle n'aurait plus qu'à dresser les assiettes.
— La cuisine se prépare la veille, a dit Lucía. C'est pour ça qu'elle ouvre vite. Mais ouvrir vite n'est pas cuisiner vite.
Qu'est-ce qui change, et qu'est-ce qui ne change pas ?
Le restaurant ne change pas : ce sont les outils de chaque rôle qui changent.
Le modèle de cet épisode, estructura-quarkus, est la même API que dans l'épisode 5 : il reçoit et consulte les commandes d'une boutique, demande au fournisseur d'inventaire combien de pièces il y a et à quel prix, et enregistre dans H2, une base en mémoire. Le paquet racine est le même, mx.habil.pedidos, et les rôles aussi. Les règles du cuisinier, les mesures exactes (Dinero, Correo) et celui qui met au propre sont passés presque sans changement.
| Rôle | Avec Spring Boot (épisode 5) | Avec Quarkus (cet épisode) |
|---|---|---|
Le serveur, api | PedidoController, ResponseEntity | PedidoResource, RestResponse |
| Le garde-manger | repository/ avec Spring Data : une interface | model/repository/ avec Panache : une classe |
Le fournisseur, client | RestClient ; délai maximal et nouvelle tentative dans la configuration | REST Client ; @Timeout et @Retry dans l'interface elle-même |
Le cahier de réclamations, exception | @RestControllerAdvice | Un ExceptionMapper et l'extension quarkus-http-problem |
| La santé | :8080/actuator/health | :9000/q/health, sur un autre port |
| L'installation du local | application.yml | application.yaml |
| Qui démarre tout | PedidosApplication, avec son main | Personne : Quarkus le génère |
estructura-quarkus/
├── pom.xml · mvnw · .mvn/ bibliotecas, construcción y el Maven del proyecto
├── Dockerfile · docs/ARCHITECTURE.md
├── herramientas/
│ ├── probar-frontera.sh la frontera que sabe fallar
│ └── medir-arranque.py el arranque y la memoria
├── src/main/java/mx/habil/pedidos/
│ ├── api/ el mesero
│ ├── facade/ el jefe de cocina
│ ├── service/ el cocinero
│ ├── client/ el proveedor de afuera
│ ├── model/
│ │ ├── request/ la comanda
│ │ ├── response/ el ticket
│ │ ├── entity/ la ficha del archivo
│ │ ├── vo/ las medidas exactas
│ │ └── repository/ la despensa
│ ├── mapper/ config/ exception/ observability/ utils/
├── src/main/resources/application.yaml
└── src/test/java/mx/habil/pedidos/ el mismo árbolPourquoi le garde-manger a-t-il déménagé dans model/repository/ ? Par une décision de la maison : le standard de Hábil pour Quarkus place le repository de Panache à côté des fiches qu'il enregistre. Les flèches ne changent pas : seul le cuisinier atteint le garde-manger.
Que veut dire « la veille » ?
Que le travail de préparer la cuisine se fait à la construction, pas à l'ouverture.
Quand une application Java démarre, quelqu'un doit lire la configuration, chercher les classes qui sont des composants, décider qui reçoit qui et assembler tout cela en mémoire. Dans un framework traditionnel, cela se fait chaque fois que l'application ouvre. Quarkus le dit en une phrase : son idée centrale est de faire « at build-time what traditional frameworks do at runtime: configuration parsing, classpath scanning, feature toggle based on classloading, and so on » [1].
Au petit resto, la cuisinière émince l'oignon avant d'ouvrir. Quarkus examine les classes quand tu construis, et au démarrage il sait déjà qui est le serveur et qui il appelle.
Cet examen, c'est ArC qui le fait, sa façon de relier les composants. Il suit la spécification Jakarta CDI (« based on the Jakarta Contexts and Dependency Injection 4.1 specification »), mais pas en entier : « It implements the CDI Lite specification, with selected improvements on top, and passes the CDI Lite TCK. It does not implement CDI Full. » [10]. CDI est le standard de Java pour ce que faisait le conteneur de Spring dans l'épisode 5 : tu déclares « le serveur a besoin d'un chef de cuisine » et quelqu'un lui en fournit un.
Dans le code, ça se remarque à peine. Le serveur reçoit ses aides par le constructeur, comme dans l'épisode 5 :
public PedidoResource(PedidoFacade facade, PedidoService service, PedidoMapper mapper) {Ce qui change, c'est le moment où c'est résolu. C'est pour cela que Quarkus n'a pas besoin d'une classe avec un main : il la génère à la construction. La porte d'entrée est target/quarkus-app/quarkus-run.jar, dans un dossier, et non un seul .jar.
Et on peut faire autre chose avec une cuisine préparée la veille : la compiler tout entière, à l'avance, en un exécutable du système d'exploitation. C'est le natif : un programme qui tourne sans la machine virtuelle Java. C'est ce que Lucía a donné à Iván.
Qu'est-ce qui change dans chaque paquet ?
Le serveur, le garde-manger, le fournisseur, le cahier de réclamations et la santé utilisent d'autres outils. Chacun garde son « jamais ».
api, le serveur
@Path("/v1/pedidos")
public class PedidoResource {
@POST
@RunOnVirtualThread
public RestResponse<PedidoResponse> crear(@Valid @NotNull CrearPedidoRequest comanda) {
PedidoResponse creado = facade.crear(comanda);
return RestResponse.ResponseBuilder.<PedidoResponse>create(RestResponse.Status.CREATED)
.header(HttpHeaders.LOCATION, "/v1/pedidos/" + creado.id())
.entity(creado)
.build();
}Quarkus REST est « a new Jakarta REST (formerly known as JAX-RS) implementation » [4] : @Path, @POST et @GET viennent de ce standard, pas de Quarkus. Dans Jakarta REST, la classe qui sert une route s'appelle une resource, une ressource. @RunOnVirtualThread demande un thread virtuel pour chaque requête, comme dans l'épisode 5, parce que le serveur attend le fournisseur ; le guide en pose la limite : « Virtual threads are useful for I/O-bound workloads only » [18].
Une différence mesurée : si tu demandes /v1/pedidos/hola, qui n'est pas un identifiant, l'épisode 5 répondait 400 et celui-ci répond 404. Ce n'est pas un oubli. La spécification de Jakarta REST l'exige : si un paramètre de la route ne peut pas être converti, « an implementation MUST generate an instance of NotFoundException (404 status) » [14]. Pour Jakarta REST, cette route n'existe pas.
Ne va jamais ici : une règle métier. Comme dans l'épisode 5.
model/repository, le garde-manger
@ApplicationScoped
public class PedidoRepository implements PanacheRepositoryBase<PedidoEntity, UUID> {
}Panache est la couche de Quarkus pour enregistrer avec Hibernate. Elle offre deux styles. Dans le premier, la fiche s'enregistre toute seule : l'entité hérite de PanacheEntity et apporte ses propres requêtes, comme Person.findByName(…). C'est le patron active record, l'enregistrement actif. Le second est celui de ce modèle : « the more classical repository pattern via PanacheRepository » [5]. La fiche est une entité JPA normale, et le garde-manger est une autre classe. On utilise PanacheRepositoryBase parce que l'identifiant est un UUID ; pour cela, le guide indique « extend PanacheRepositoryBase instead of PanacheRepository and specify your ID type » [5].
Pourquoi un garde-manger à part ? À cause de la troisième règle de l'épisode 5 : ce qui entre, ce qui est enregistré et ce qui sort sont des choses distinctes. Si la fiche enregistre et consulte aussi, elle apporte avec elle des méthodes comme persist() : quiconque a une fiche en main pourrait tenter d'écrire dans la base, même le serveur, et dans une transaction il y arriverait [5]. Avec un garde-manger à part, seul le cuisinier l'atteint, et le test d'architecture y veille.
Ne va jamais ici : une décision. Et jamais : extends PanacheEntity sur la fiche. C'est la première erreur de la liste, et la plus silencieuse.
client, le fournisseur extérieur
@RegisterRestClient(configKey = "inventario")
@Path("/productos")
public interface InventarioApi {
@GET
@Path("/{sku}.json")
@Timeout(2000)
@Retry(maxRetries = 2, delay = 200, jitter = 50,
retryOn = {TimeoutException.class, ProcessingException.class})
@ExponentialBackoff(factor = 2)
InventarioClient.Producto producto(@PathParam("sku") String sku);
}Dans l'épisode 5, le client était une classe qui appelait en HTTP. Ici, c'est une interface : tu déclares la route et Quarkus écrit l'appel [6]. L'adresse du fournisseur va dans application.yaml, sous la clé inventario.
Les deux précautions habituelles sont dans l'interface elle-même, avec des annotations de MicroProfile Fault Tolerance. L'extension en offre plusieurs, comme @CircuitBreaker [7] ; cette interface en utilise trois : @Timeout, @Retry et @ExponentialBackoff. Deux secondes de délai maximal par tentative et jusqu'à deux nouvelles tentatives : trois tentatives au total. On ne recommence qu'en cas de délai dépassé ou de panne réseau. Un « n'existe pas » du fournisseur est une réponse et ne se répète pas. Mesuré avec le fournisseur éteint : l'API répond 503, avec "error_code":"PROVEEDOR_NO_DISPONIBLE", en une demi-seconde (0.534s), après les trois tentatives.
Ne va jamais ici : une règle de la commande. Ni un appel sans délai maximal.
exception, le cahier de réclamations
@Provider
public class PedidosExceptionMapper extends ExceptionMapperBase<PedidosException>
implements ExceptionMapper<PedidosException> {
@Override
protected HttpProblem toProblem(PedidosException queja) {
return queja.codigo().aProblema(queja.getMessage());
}
}La forme de la réponse est celle de l'épisode 5 : Problem Details, la RFC 9457 [16]. Elle vient d'une extension de la communauté, quarkus-http-problem : « Unified error responses for Quarkus REST APIs via Problem Details for HTTP APIs (RFC9457 & RFC7807) » [15]. Un ExceptionMapper est la pièce de Jakarta REST qui transforme une exception en réponse [4]. Mesuré, en demandant quatre tasses quand il y en a trois :
{"type":"https://pedidos.example/errors/sin_existencias","status":409,
"title":"No hay existencias suficientes","detail":"De TAZA-01 se pidieron 4 y hay 3",
"instance":"/v1/pedidos","error_code":"SIN_EXISTENCIAS",
"request_id":"e8cc3ea5-44a3-47ef-8e39-275e4e584861"}Le request_id est le même que celui de l'en-tête X-Request-ID et du journal : avec lui, on retrouve la visite. Ne va jamais ici : un format d'erreur maison.
La santé, sur un autre port
Quarkus publie la santé sur /q/health/live et /q/health/ready [8]. Le modèle l'envoie, avec les métriques [20], à l'interface d'administration : avec quarkus.management.enabled=true, ces routes sortent sur le port 9000 et non sur celui de l'API [9].
curl -s localhost:9000/q/health/readyElle répond (la sortie tient sur plusieurs lignes ; ici, elle est regroupée) :
{"status":"UP","checks":[{"name":"Database connections health check","status":"UP","data":{"<default>":"UP"}}]}Mesuré : curl -s localhost:8080/q/health répond 404. Ce qui est à l'intérieur ne sort pas par la porte des clients. C'est comme la cuisine du petit resto : l'inspecteur entre par la porte de service, pas par la salle.
config, l'installation du local
application.yaml avec l'extension quarkus-config-yaml [11]. Il porte un avertissement sur sa première ligne, parce que ça nous est arrivé : une clé mal écrite n'arrête pas Quarkus. On le voit dans l'erreur 4.
À quelle vitesse ouvre-t-elle ?
Mesuré : le natif crée sa première commande en 46 millisecondes et pèse 60 MiB. Le construire a pris 80 secondes et a demandé 4 GiB.
Ce qui a été mesuré. Le temps entre le lancement du processus et la première réponse 201 à un POST /v1/pedidos. Il ne suffit pas que le port s'ouvre : cette réponse oblige à appeler deux fois le fournisseur d'inventaire et à enregistrer dans H2. Juste après avoir reçu ce 201, on lit avec ps la mémoire qu'occupe le processus (RSS, resident set size : la mémoire physique qu'il a prise). Cinq exécutions d'affilée pour chacune, et la médiane. Le script est herramientas/medir-arranque.py, et il vient avec le modèle pour que tu le refasses.
Où. Un Mac avec Apple Silicon (macOS arm64, 10 cœurs, 32 GB), le 18 novembre 2026. Les deux en JVM avec Java 25 (Temurin 25.0.5+8), sans options de mémoire ; Quarkus 3.40.1.2 et Spring Boot 4.1.2, le modèle de l'épisode 5.
| La même API, en… | Première réponse (médiane de 5) | Mémoire (RSS) | Les cinq exécutions |
|---|---|---|---|
| Spring Boot, JVM | 2 241 ms | 437 MiB | 2181, 2241, 2377, 2301, 2207 ms |
| Quarkus, JVM | 1 220 ms | 270 MiB | 1515, 1250, 1220, 1145, 1175 ms |
| Quarkus, natif | 46 ms | 60 MiB | 150, 67, 46, 38, 44 ms |
Nous avons refait la série sur le même Mac, avec Temurin 25.0.4+7 : Spring Boot, 2 617 ms et 427 MiB ; Quarkus sur la JVM, 1 378 ms et 266 MiB ; le natif, 47 ms et 60 MiB. Les millisecondes de la JVM bougent d'une série à l'autre ; l'ordre, non.
Ce que ça coûte. Construire le natif a demandé GraalVM, le compilateur qui transforme la cuisine préparée en exécutable. Dans SDKMAN, il s'installe comme le candidat 25.5.5.0+3-graalce [21]. Sur le même Mac, cela a pris 80 secondes (dont 72 de compilation), a atteint 4,11 GiB de mémoire et a laissé un exécutable de 78 MiB, qui ne sert que pour le système où il a été construit : celui d'un Mac ne tourne pas sous Linux. Celle en JVM se construit en quelques secondes. Le guide officiel le confirme : « native compilation takes minutes, JVM builds take seconds » [2].
Ce que ce tableau ne te dit pas. Le guide de Quarkus a sa propre comparaison, avec son application et sa machine : dans son banc d'essai, le natif arrive à la première requête en 581 ms contre 4 417 pour la JVM et occupe 95 MiB contre 304. Mais il sert 5 411 requêtes par seconde contre 13 265 : « ~59% below JVM » [2]. La raison, c'est le même guide qui la donne : sur la JVM, le compilateur optimise pendant que l'application tourne, et dans les services de longue durée cela l'emporte sur le natif [2]. Nous n'avons pas mesuré de requêtes par seconde, et c'est pourquoi nous ne donnons pas de chiffre à nous.
C'est la question de Lucía. Le natif ouvre vite et occupe peu. Cuisiner vite, pendant des heures, c'est autre chose.
Alors, lequel ? Le modèle tourne en JVM : il se construit en quelques secondes, se vérifie avec les outils habituels et démarre en un peu plus d'une seconde, ce qui, pour une API qui vit des jours, ne pèse rien. Le natif vaut la peine quand le démarrage et la mémoire pèsent vraiment : des fonctions qui naissent à chaque requête, beaucoup de petites répliques, monter en charge à partir de zéro. Dans ce modèle, c'est le même code : décider, c'est changer la commande de construction, pas les couches. Dans une autre application, tu devras peut-être déclarer ce qui se charge par réflexion [2][3]. Et chez Hábil, cela se décide par écrit, avec la mesure qui le justifie.
Les flèches vont-elles toujours vers l'intérieur ?
Oui, et le même test y veille. Cette fois, le script sème quatre erreurs au lieu d'une.
Pour Java, que le cuisinier connaisse le serveur n'est toujours pas une erreur : ça compile. La règle est surveillée par CapasTest, écrit avec ArchUnit, qui examine les classes compilées [17]. Les couches sont les mêmes que dans l'épisode 5 :
.whereLayer("api").mayNotBeAccessedByAnyLayer()
.whereLayer("facade").mayOnlyBeAccessedByLayers("api")
.whereLayer("service").mayOnlyBeAccessedByLayers("api", "facade")
.whereLayer("repository").mayOnlyBeAccessedByLayers("service")
.whereLayer("client").mayOnlyBeAccessedByLayers("facade", "service")Et une règle à part : aucune classe de api ne peut dépendre d'une entity. Le serveur remet le ticket, jamais la fiche.
herramientas/probar-frontera.sh travaille sur une copie temporaire. D'abord, il lance le contrôle : le projet tel quel doit passer. Ensuite, il sème quatre erreurs, une à la fois. Chacune doit compiler, et CapasTest doit échouer sur une seule règle, pour la raison exacte. Voici la sortie réelle, raccourcie :
1/5 control: el proyecto tal como está; el cocinero no conoce al mesero y el mesero no entrega la ficha
✅ compiló y CapasTest pasó: 4 reglas, 0 fallas
2/5 violación: se siembra en PedidoService un método que recibe un PedidoResource
✅ CapasTest falló en una sola regla, lasFlechasSoloVanHaciaAdentro
3/5 fuga: se siembra en PedidoResource un método que entrega la PedidoEntity tal cual
✅ CapasTest falló en una sola regla, elMeseroNoConoceLaFichaDelArchivo
4/5 fuga: la misma PedidoEntity, escondida en una List<PedidoEntity>
✅ CapasTest falló en una sola regla, elMeseroNoConoceLaFichaDelArchivo
5/5 fuga: la misma PedidoEntity, escondida en una RestResponse<PedidoEntity>
✅ CapasTest falló en una sola regla, elMeseroNoConoceLaFichaDelArchivo
✅ frontera: se sostiene (la violación y las tres fugas salieron en rojo, cada una por su razón)Et si le script mentait ? Nous l'avons saboté. Avec la règle de la fiche pointant vers un autre paquet, il s'arrête au rouge à la première fuite. Sans la règle de couche de api, il s'arrête à la violation. Un script qui ne sait pas échouer ne démontre rien.
Les tests sont 82, comptés dans les rapports de target/surefire-reports/, pas dans le BUILD SUCCESS. Ceux qui lancent l'application utilisent @QuarkusTest. Ceux qui partagent un profil réutilisent la même instance de Quarkus ; un test avec un autre profil, comme celui du fournisseur éteint, la redémarre [23].
Quelles sont cinq erreurs fréquentes ?
Trois viennent d'un rôle qui fait le travail d'un autre, comme dans l'épisode 5. Deux sont nouvelles : confondre ouvrir et cuisiner, et se fier à ce qui ne prévient pas.
1. La fiche qui est aussi le garde-manger
L'entité hérite de PanacheEntity et s'enregistre toute seule.
C'est la forme que le guide de Panache enseigne en premier [5], et elle fonctionne. Nous l'avons mesuré sur un clone du modèle : nous avons fait hériter PedidoEntity de PanacheEntityBase et avons tout lancé. 82 sur 82 au vert. Aucun test du modèle ne le voit, parce que les flèches restent correctes : la fiche n'importe personne. Ce qui a changé, c'est que la fiche apporte maintenant persist(), et quiconque a une fiche en main, dans une transaction, pourrait écrire dans la base.
Ce qui la trahit, c'est une recherche :
grep -rn 'extends PanacheEntity' src/mainZéro résultat, c'est ce que tu veux. C'est la tâche de lundi.
2. Tout passer en natif parce qu'il ouvre vite
Mesurer le démarrage et conclure sur les performances.
C'est celle d'Iván. Le natif ouvre en millisecondes, mais dans le banc d'essai du guide officiel il sert ~59 % de requêtes par seconde en moins, et sa construction prend des minutes et demande des gigaoctets de mémoire [2]. Une question la trahit : qu'est-ce qui te coûte vraiment, ouvrir ou servir ?
3. Le binaire qui démarre et meurt à sa première commande
Tester le natif avec la santé et non avec une vraie commande.
En compilant en natif, n'entre que ce que le compilateur voit utilisé. Ce qu'une bibliothèque charge par son nom, sur le moment, peut rester dehors. Le guide de Quarkus décrit le pire cas : il n'y a pas d'exception, mais « the JSON result would be completely empty » [3]. La santé peut répondre UP pendant que la première commande sort vide. C'est pourquoi le modèle ne valide pas le natif parce qu'il démarre : il lui demande une commande qui appelle le fournisseur et enregistre dans la base. Nous l'avons mesuré ainsi : le natif a répondu 201, 404, 409, 422 et 400 avec son Problem Details, et 503 avec le fournisseur éteint.
4. Une clé ignorée en silence
Une configuration mal écrite n'échoue pas : elle ne fait rien.
Ça nous est arrivé avec le modèle. Pour raccourcir le délai maximal dans les tests, nous avons écrit la clé avec le nom de l'interface, InventarioApi/producto. Quarkus ne s'est pas plaint, et le délai maximal est resté à 2 secondes. La bonne clé porte le nom de la classe que Quarkus génère pour l'interface, InventarioApi$$CDIWrapper/producto. Quarkus prévient bien d'une clé qu'il ne reconnaît pas, avec « Unrecognized configuration key », mais seulement pour celles qui commencent par quarkus. ; mesuré avec une fausse clé de chaque type. Ce qui la trahit, c'est un test qui dépend de cette clé : celui du délai maximal passe au rouge si la clé ne s'applique pas.
5. Copier les annotations de Spring
Chercher @RestController, @Service et @Autowired dans un projet Quarkus.
Dans Quarkus, le serveur est une resource de Jakarta REST, et les composants se relient avec CDI [4][10]. Quarkus a des extensions qui comprennent certaines annotations de Spring [19], mais le modèle ne les utilise pas : si le projet est en Quarkus, il s'écrit comme du Quarkus, et celui qui le lira plus tard trouvera ce qu'enseigne la documentation officielle. Si une équipe décide de les utiliser, que ce soit par écrit, et non parce que quelqu'un a copié un exemple.
| Erreur | Ce qui la trahit | Source |
|---|---|---|
| 1. La fiche qui est aussi le garde-manger | grep -rn 'extends PanacheEntity' src/main | [5] · mesure |
| 2. Tout en natif parce qu'il ouvre vite | Les requêtes par seconde, pas seulement le démarrage | [2] |
| 3. Le natif qui meurt à sa première commande | Une vraie commande, pas la santé | [3] · mesure |
| 4. Une clé qui ne fait rien | Un test qui dépend de cette clé | mesure |
| 5. Des annotations de Spring dans Quarkus | @RestController ou @Autowired dans src/main | [4][10][19] |
Exercice : peux-tu cacher la fiche dans le ticket ?
Tu vas faire en sorte que le serveur remette la fiche d'archive dans une réponse, voir que Java l'accepte, et voir comment le test et le script te préviennent.
Il te faut Java 25 (java -version), Git 2.23 ou plus récent (pour git restore), bash et curl ; environ 25 minutes. Pas Maven : le projet l'apporte. Si tu n'as pas encore Java 25, l'épisode 5 et le README du modèle expliquent comment l'installer avec SDKMAN ; sous Windows, utilise WSL. Le natif n'est pas nécessaire pour l'exercice.
Étape 1. Clone le modèle et vérifie que tout est au vert.
git clone https://github.com/HabilMX/estructura-quarkus
cd estructura-quarkus
./mvnw verify
bash herramientas/probar-frontera.shLa première fois, c'est long : il télécharge Maven et les bibliothèques. Tu dois voir Tests run: 82, Failures: 0, Errors: 0, Skipped: 0, puis BUILD SUCCESS et, à la fin du script, ✅ frontera: se sostiene.
Utilise ce clone seulement pour t'exercer. Ainsi, tout changement que tu y vois vient de l'exercice.
Étape 2. Prédis avant de toucher. Tu vas ajouter au serveur, PedidoResource, une route qui renvoie la PedidoEntity dans une RestResponse. Note : est-ce que ça compile ? Que dit CapasTest ? Et le script de la frontière ?
Étape 3. Cache la fiche. La première ligne retire la dernière accolade de la classe et laisse une copie .bak ; la seconde ajoute la route et ferme la classe. La syntaxe fonctionne sous macOS et sous Linux ; l'exercice complet a été testé sous macOS.
sed -i.bak '$d' src/main/java/mx/habil/pedidos/api/PedidoResource.java
printf ' @GET\n @Path("/{id}/ficha")\n public org.jboss.resteasy.reactive.RestResponse<mx.habil.pedidos.model.entity.PedidoEntity> ficha(@PathParam("id") UUID id) {\n return org.jboss.resteasy.reactive.RestResponse.ok(service.buscar(id));\n }\n}\n' \
>> src/main/java/mx/habil/pedidos/api/PedidoResource.java
./mvnw -q test-compile
./mvnw -q test -Dtest=CapasTesttest-compile se termine sans rien dire : ça a compilé. Le test, non. Parmi beaucoup de lignes, celles qui comptent :
Tests run: 4, Failures: 1, Errors: 0, Skipped: 0
Method <mx.habil.pedidos.api.PedidoResource.ficha(java.util.UUID)> has generic return type <org.jboss.resteasy.reactive.RestResponse<mx.habil.pedidos.model.entity.PedidoEntity>> with type argument depending on <mx.habil.pedidos.model.entity.PedidoEntity> in (PedidoResource.java:0)ArchUnit ne s'est pas arrêté au type que renvoie la méthode, mais à ce dont elle dépend : la fiche était cachée dans la réponse, et il l'a quand même trouvée.
Étape 4. Interroge le script.
bash herramientas/probar-frontera.shIl passe au rouge, sans dépasser le contrôle :
❌ el control NO pasó: tu proyecto, tal como está, ya rompe una regla de CapasTest:C'est le contrôle qui travaille : il ne peut pas démontrer que le test sait échouer si ton projet le fait déjà échouer.
Étape 5. Remets seulement ce que tu as touché. D'abord, regarde ce qui a changé :
git diff --stat -- src/main/java/mx/habil/pedidos/api/PedidoResource.javaTu dois voir 1 file changed, 5 insertions(+) : la nouvelle route. Si tu vois autre chose, c'est à toi : sauvegarde-le avant de continuer. S'il n'y a que l'exercice, remets ce fichier. git restore ne touche que les chemins que tu lui donnes [22] :
git restore src/main/java/mx/habil/pedidos/api/PedidoResource.java
bash herramientas/probar-frontera.sh
git status --shortLa frontière repasse au vert, et git status montre ce qui reste, la copie qu'a faite sed :
?? src/main/java/mx/habil/pedidos/api/PedidoResource.java.bakGarde-la jusqu'à être sûr de ne plus en avoir besoin. Ensuite, efface-la avec rm -i, qui demande avant.
Comment savoir que tu l'as bien fait : tu as lancé six fois et vu trois issues. Vert, quatre fois : les deux de l'étape 1, test-compile à l'étape 3 et la frontière de l'étape 5. Rouge du test, une fois : Failures: 1 à l'étape 3. Et le rouge du script, « el control NO pasó », à l'étape 4. Si, à l'étape 3, test-compile signale une erreur, vérifie que PedidoResource.java se termine par une seule accolade }.
Pour aller plus loin (facultatif) : transforme la fiche en garde-manger. Dans PedidoEntity, fais hériter la classe de PanacheEntityBase (ajoute import io.quarkus.hibernate.orm.panache.PanacheEntityBase; et remplace public class PedidoEntity { par public class PedidoEntity extends PanacheEntityBase {). Avant, prédis : combien de tests échouent ? Réponse mesurée : aucun, 82 sur 82. Lance grep -rn 'extends PanacheEntity' src/main : lui, il la trouve. Remets comme à l'étape 5.
À retenir
Trois questions à poser à ton dépôt cette semaine.
- Combien de fiches de ton projet héritent de
PanacheEntity? Chacune est une entité qui apporte ses propres méthodes pour s'enregistrer. - Si tu utilises le natif, quelle mesure l'a justifié : le démarrage, la mémoire ou les requêtes par seconde ? Est-ce resté écrit ?
- Quel test passe au rouge si une clé de ta configuration cesse de s'appliquer ? Si la réponse est « aucun », cette clé ne fait peut-être rien depuis des mois.
Et ensuite ?
Le restaurant a aussi une salle.
Un vendredi, on a demandé à Iván de déplacer un bouton sur l'écran où la boutique voit ses commandes. Le projet était en React. Il a ouvert le dossier src/ et a trouvé quatre-vingts fichiers en vrac, tous au même niveau : boutons, écrans, appels à l'API, tout mélangé.
Il avait appris à demander à qui revient chaque travail. Cette fois, il ne trouvait même pas les rôles. Le dimanche 13 décembre, dans l'épisode 7, le dernier de la série : comment organiser un frontend avec React, ce qui va dans chaque dossier, et le modèle qui le vérifie.
Le modèle et le cours
- Modèle : github.com/HabilMX/estructura-quarkus. Il s'utilise comme modèle GitHub ou se clone. Le README explique chaque paquet avec son « jamais », le chemin d'une commande, ce qui a changé par rapport à Spring Boot, comment mesurer le démarrage et la mémoire, ce qu'il n'apporte pas (authentification, une vraie base, contrat OpenAPI), quand ajouter chaque chose et comment retirer l'exemple. Le code est sous MIT ; le texte et les explications, sous CC BY-SA 4.0.
- Pour le voir travailler : le README fournit les
curl. Le fournisseur d'inventaire d'exemple est un dossier avec deux fichiers JSON, servi avecjwebserver, que le JDK apporte déjà. La base est H2, en mémoire : le plus simple qui tourne du premier coup ; les données s'effacent à l'arrêt. La santé et les métriques, sur le port 9000. - Versions : Java 25 avec Temurin 25.0.5+8. Quarkus 3.40.1.2 : la 3.40 est sa version à support long la plus récente [13], et une version à support long est maintenue 12 mois, avec une nouvelle tous les six mois [12]. Maven par le Wrapper. GraalVM CE
25.5.5.0+3-graalce, seulement pour le natif. Testé sur macOS arm64. Pas encore sous Linux : la CI est écrite pour Ubuntu et macOS, et elle tournera quand le dépôt public existera. - Cours de Java de Hábil : si les
record, Maven ou les tests avec JUnit sont nouveaux pour toi, commence par là : Cours de Java. Et si tu n'as pas lu l'épisode 5, lis-le d'abord : celui-ci tient pour acquis les rôles du restaurant.
J'écris à partir de ce que nous voyons tous les jours chez Hábil, où nous construisons des systèmes pour la banque, l'assurance et les entreprises au Mexique. Si, au travail ou à l'école, ton équipe tombe sur un dépôt que personne ne sait par où prendre, parlons-en : habil.mx
Que fait Hábil ?
Nous enseignons la programmation avec ce que nous utilisons pour construire : du code testé, expliqué et ouvert.
Cette série naît du même endroit que nos cours. Le Cours de Java enseigne le Java d'aujourd'hui : des types qui expriment le modèle, des tests, la concurrence et un programme terminé, empaqueté dans un JAR, et nous le publions en accès ouvert, sous licence Creative Commons ; sa leçon 3 présente les record et sa leçon 6 le projet avec Maven, la même base qu'utilise le modèle de cet article. Et le catalogue compte d'autres cours de programmation, gratuits, avec du code testé et expliqué pas à pas.
Découvre le Cours de Java et le catalogue des Cours de programmation.
Si ton équipe hérite d'un système que personne ne sait par où prendre, ou doit en construire un qui puisse continuer à être maintenu, nous le faisons aussi : découvre Construire votre système sur mesure. Demande ton premier échange, sans frais. Nous y examinons s'il vaut mieux configurer ce que ton équipe a déjà, utiliser un produit ou construire, et ce qu'elle recevrait dans chaque cas. Écris-nous sur WhatsApp.
Sources consultées le 18 novembre 2026. Les citations en anglais sont reproduites telles quelles.
Références
- Quarkus, « Container First » : « Build Time Processing ». https://quarkus.io/container-first/
- Quarkus, « Building a Native Executable » : « Comparing JVM, Leyden AOT, and native modes » (banc d'essai du 21 avril 2026, Quarkus 3.34.3, JDK 25.0.2, 4 CPU). https://quarkus.io/guides/building-native-image
- Quarkus, « Tips for writing native applications ». https://quarkus.io/guides/writing-native-applications-tips
- Quarkus, « Writing REST Services with Quarkus REST » : « Exception mapping ». https://quarkus.io/guides/rest
- Quarkus, « Simplified Hibernate ORM with Panache » : « Solution 1: using the active record pattern » et « Solution 2: using the repository pattern ». https://quarkus.io/guides/hibernate-orm-panache
- Quarkus, « Using the REST Client ». https://quarkus.io/guides/rest-client
- Quarkus, « SmallRye Fault Tolerance ». https://quarkus.io/guides/smallrye-fault-tolerance
- Quarkus, « SmallRye Health ». https://quarkus.io/guides/smallrye-health
- Quarkus, « Management interface reference ». https://quarkus.io/guides/management-interface-reference
- Quarkus, « Contexts and Dependency Injection » (référence d'ArC). https://quarkus.io/guides/cdi-reference
- Quarkus, « YAML configuration ». https://quarkus.io/guides/config-yaml
- M. Rydahl Andersen, « Long-Term Support (LTS) for Quarkus », blog de Quarkus, 6 juillet 2023. https://quarkus.io/blog/lts-releases/
- G. Smet, « Quarkus 3.40 LTS - new LTS version », blog de Quarkus, 30 septembre 2026. https://quarkus.io/blog/quarkus-3-40-released/
- Eclipse Foundation, « Jakarta RESTful Web Services 3.1 », conversion des paramètres. https://jakarta.ee/specifications/restful-ws/3.1/jakarta-restful-ws-spec-3.1
- Quarkiverse, « quarkus-http-problem », GitHub. https://github.com/quarkiverse/quarkus-http-problem
- M. Nottingham, E. Wilde et S. Dalal, « RFC 9457: Problem Details for HTTP APIs », IETF, juillet 2023. https://www.rfc-editor.org/rfc/rfc9457.html
- ArchUnit, « ArchUnit User Guide » : « Layer Checks ». https://www.archunit.org/userguide/html/000_Index.html
- Quarkus, « Virtual thread support reference ». https://quarkus.io/guides/virtual-threads
- Quarkus, « Quarkus extension for Spring DI API ». https://quarkus.io/guides/spring-di
- Quarkus, « Micrometer Metrics ». https://quarkus.io/guides/telemetry-micrometer
- SDKMAN, candidats Java pour macOS arm64 (
25.5.5.0+3-graalce). https://api.sdkman.io/2/candidates/java/darwinarm64/versions/list?installed= - Git, « git-restore ». https://git-scm.com/docs/git-restore
- Quarkus, « Testing your application ». https://quarkus.io/guides/getting-started-testing
Votre activité fait face à ces défis ?
Vous préférez l'e-mail ? Écrivez-nous à hola@habil.mx