La structure d'un projet (5) : la couche qui ne faisait rien
Par Dorian Chávez · cofondateur et Chief Executive Officer de Hábil ·
Quatre couches et une facade qui ne fait que passer l'appel. Ce qui va dans chaque paquet d'une API Spring Boot, quand la facade est de trop, et un modèle.
La structure d'un projet · épisode 5 sur 7 · Java avec Spring Boot
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
- Spring Boot n'exige aucune façon de ranger le code [1]. Les couches sont une décision ; voici celle du modèle, avec son pourquoi.
- Chaque paquet est un rôle dans un restaurant :
apiest le serveur,servicele cuisinier,repositoryle garde-manger. Et chaque rôle a quelque chose qu'il ne fait jamais. - La
facade, le chef de cuisine, se justifie quand elle coordonne deux acteurs ou plus. Si sa méthode ne fait qu'en appeler une autre, elle est de trop. - Pour Java, que le cuisinier connaisse le serveur n'est pas une erreur : ça compile. C'est un test d'architecture qui le détecte [12].
- Tu repars avec un modèle qui tourne du premier coup, avec un script qui démontre cette frontière en passant au rouge quand il le faut.
- Pour lundi : ouvre ta
facadeet compte combien de méthodes ne font qu'en appeler une autre.
Dans cet article
- Que s'est-il passé jeudi à 16:40 ?
- Que va-t-il dans chaque paquet ?
- Quand faut-il la facade, et quand non ?
- Quelles sont les trois règles ?
- Quelles sont cinq erreurs fréquentes ?
- Exercice : peux-tu faire que le cuisinier appelle le serveur ?
- À retenir
- Et ensuite ?
- Le modèle et le cours
- Que fait Hábil ?
- Références
Que s'est-il passé jeudi à 16:40 ?
Iván a ajouté un champ à une réponse, a touché quatre fichiers et a trouvé une couche qui ne faisait rien.
Jeudi, 16:05. Troisième étage.
Un mois après l'alias. Première API en Java, avec Spring Boot : les commandes d'une boutique. La mission tenait en une ligne : « Que la consultation d'une commande dise aussi quand elle a été créée ».
Quelqu'un d'autre avait laissé le projet. Quatre dossiers portant un nom de couche :
src/main/java/…/pedidos/
api/
facade/
service/
repository/La donnée était déjà dans la table. Pour qu'elle arrive jusqu'au JSON, Iván a touché quatre fichiers, un par dossier. Dans trois, il a copié le champ d'une classe à une autre. Dans le quatrième, la facade, il s'est arrêté :
public PedidoResponse buscar(UUID id) {
return service.buscar(id);
}Une méthode qui ne faisait qu'en appeler une autre. Elle recevait la même chose et renvoyait la même chose. Il a regardé les autres méthodes de la classe : il y en avait six, et cinq faisaient ça.
Jeudi, 16:40.
Ça a compilé. Les tests sont passés. Avant de pousser le changement, il a écrit à Lucía.
— Quatre fichiers pour déplacer une donnée. Et une couche ne fait rien : elle appelle la suivante, et c'est tout. Je l'enlève ?
— Combien d'acteurs cette méthode appelle-t-elle ? a-t-elle répondu.
— Un seul. Le service.
— Et celle qui crée une commande ?
Iván l'a ouverte. Celle-là était différente : elle demandait d'abord le prix à un autre système, puis elle appelait le service.
— Deux.
— Alors dans l'une, le chef de cuisine est de trop, et dans l'autre, non.
— Quel chef de cuisine ?
— Demain, on mange au petit resto d'en face. Regarde bien qui fait quoi.
Iván a regardé les quatre dossiers. Il avait cru que c'étaient quatre étapes obligatoires. C'étaient quatre métiers.
Que va-t-il dans chaque paquet ?
Ce qui revient à un rôle dans un restaurant, et rien de plus. Les couches, ce n'est pas Spring Boot qui les demande : c'est une décision.
La documentation de Spring Boot le dit d'entrée : « Spring Boot does not require any specific code layout to work » [1]. Son propre exemple ne range même pas par couches : il met un dossier pour les clients et un autre pour les commandes [1]. Ce qu'elle recommande, en revanche, c'est où va la classe qui démarre l'application : « in a root package above other classes » [1]. C'est à partir de ce paquet, vers le bas, que Spring cherche les composants et les entités.
D'où viennent alors api, service et repository ? D'une habitude que Spring porte dans ses annotations : @Controller, @Service et @Repository existent pour les couches « persistence, service, and presentation » [2]. Chez Hábil, c'est une pratique de la maison : un paquet par rôle, et les dépendances dans un seul sens. Ce n'est pas la seule bonne façon. C'en est une qui tient dans un repas.
Le modèle de cet épisode, estructura-java-spring-boot, est l'API des commandes d'une boutique. Son paquet racine est mx.habil.pedidos : le domaine à l'envers et le nom de l'application [1].
estructura-java-spring-boot/
├── pom.xml bibliotecas y construcción
├── mvnw · .mvn/ el Maven del proyecto
├── Dockerfile la imagen
├── docs/ARCHITECTURE.md las capas y las decisiones
├── herramientas/probar-frontera.sh
├── src/main/java/mx/habil/pedidos/
│ ├── PedidosApplication.java aquí arranca todo
│ ├── api/ el mesero
│ ├── facade/ el jefe de cocina
│ ├── service/ el cocinero
│ ├── repository/ la despensa
│ ├── client/ el proveedor de afuera
│ ├── model/ los papeles que pasan de mano en mano
│ │ ├── request/ la comanda
│ │ ├── response/ el ticket
│ │ ├── entity/ la ficha del archivo
│ │ └── vo/ las medidas exactas
│ ├── mapper/ el que pasa en limpio
│ ├── config/ la instalación del local
│ ├── exception/ el libro de quejas
│ ├── observability/ las cámaras y la bitácora
│ └── utils/ el cajón de herramientas
├── src/main/resources/application.yml
└── src/test/java/mx/habil/pedidos/ el mismo árbolsrc/main et src/test sont la disposition standard de Maven, l'outil qui construit le projet : elle permet à qui connaît un projet de « immediately feel at home in another » [14]. mvnw, c'est le Maven Wrapper : il télécharge la version de Maven que le projet déclare, et personne ne l'installe à la main [15].
Allons rôle par rôle. Chacun vient avec son exemple tiré du modèle et une ligne : ce qui n'y va jamais.
Qui sert les clients ?
api, le serveur. Il reçoit le bon de commande, vérifie qu'il est bien rempli et le transmet. Il ne cuisine pas.
@PostMapping
public ResponseEntity<PedidoResponse> crear(@Valid @RequestBody CrearPedidoRequest comanda) {
PedidoResponse creado = facade.crear(comanda);
return ResponseEntity.created(URI.create("/v1/pedidos/" + creado.id())).body(creado);
}Tout ce qui est HTTP vit ici : la route, le verbe, le 201. @Valid, c'est la vérification : si le bon de commande est mal rempli, Spring lance MethodArgumentNotValidException [5] et la cuisine n'en sait même rien. N'y va jamais : une règle métier. Un if sur une donnée de la commande revient au cuisinier.
service, le cuisinier. C'est ici que vivent les règles. Le modèle en a deux : on n'accepte pas une commande s'il manque une pièce, et le total, c'est le prix multiplié par la quantité.
if (linea.cantidad() > linea.existencias()) {
throw new PedidosException(CodigoError.SIN_EXISTENCIAS,
"De %s se pidieron %d y hay %d".formatted(linea.sku(), linea.cantidad(), linea.existencias()));
}
total = total.mas(linea.importe());N'y va jamais : ni HTTP ni JSON. Le cuisinier ne sait pas si la commande est arrivée par une appli ou par téléphone ; c'est pour ça que ses tests tournent sans serveur et sans base de données.
repository, le garde-manger. Il range et il rapporte.
public interface PedidoRepository extends JpaRepository<PedidoEntity, UUID> {
}C'est toute l'interface. Spring Data se charge du « creating Repository implementations directly from interfaces » [7]. N'y va jamais : une décision. Si une commande peut être enregistrée, c'est le cuisinier qui le dit.
client, le fournisseur extérieur. Un autre système, sur une autre machine. Dans le modèle, c'est l'inventaire : combien de pièces il y a et à quel prix. On l'appelle avec deux précautions. Un délai maximal : application.yml déclare une seconde pour se connecter et deux pour lire [8]. Et une nouvelle tentative, seulement face à une erreur réseau de celles que Spring appelle ResourceAccessException ; un 404 du fournisseur est une réponse et on ne le répète pas. Spring Framework 7 apporte déjà la nouvelle tentative dans son noyau [9]. Deux nouvelles tentatives, ce sont trois appels : « total attempts = 1 initial attempt + maxRetries attempts » [9]. N'y va jamais : une règle de la commande. Ni un appel sans délai maximal.
facade, le chef de cuisine. Il coordonne. C'est la question d'Iván, et elle a sa section.
Quels papiers passent de main en main ?
request est le bon de commande, response le ticket et entity la fiche d'archive. Trois papiers, même s'ils disent presque la même chose.
public record CrearPedidoRequest(
@NotBlank @Email @Size(max = 254) String correo,
@NotEmpty @Size(max = 20) List<@Valid @NotNull Linea> lineas) {Le bon de commande et le ticket sont des record : des classes qui ne font que porter des données, avec leurs champs finaux [16]. Les annotations viennent de Jakarta Validation [6]. Le bon de commande ne porte pas de prix : le prix, c'est le fournisseur qui le met, pas le client. Le ticket ne porte pas l'adresse e-mail : personne ne l'a demandée. La fiche, PedidoEntity, a la forme de la table, et c'est une classe normale parce que la spécification de JPA dit qu'un record « may not be designated as an entity » [17]. Jamais : que la fiche sorte par la porte. Le serveur remet le ticket.
Et les autres paquets ?
vo, la mesure exacte. vo veut dire value object, objet valeur : on le reconnaît à ce qu'il vaut, pas à un id ; deux Dinero de 100 centimes sont la même somme. Dinero n'est pas un long isolé : c'est une somme en centimes qui n'est jamais négative. S'il existe, il est déjà valide, et personne ne le revérifie. Pareil pour Correo. N'y va jamais : quelque chose de Spring ou d'une autre couche.
mapper, celui qui met au propre. Il copie de la fiche au ticket, champ par champ. N'y va jamais : un if qui décide quelque chose.
config, l'installation du local. L'horloge, le téléphone pour appeler le fournisseur, combien de fois on retente. On l'installe une fois, à l'ouverture. N'y va jamais : ni règles ni routes.
exception, le cahier de réclamations. Tout ce qui peut mal tourner a un code dans un catalogue, et un seul endroit construit la réponse. La forme n'est pas la nôtre : c'est Problem Details, la RFC 9457, qui existe « to avoid the need to define new error response formats for HTTP APIs » [4], et Spring l'apporte déjà [3]. Mesuré dans le modèle, en demandant quatre tasses quand il y en a trois :
{"detail":"De TAZA-01 se pidieron 4 y hay 3","instance":"/v1/pedidos","status":409,
"title":"No hay existencias suficientes",
"type":"https://pedidos.example/errors/sin_existencias","error_code":"SIN_EXISTENCIAS"}N'y va jamais : un format d'erreur maison.
observability, les caméras et le journal. Chaque requête reçoit un numéro, qui apparaît sur chaque ligne du journal et revient au client dans X-Request-ID. N'y va jamais : une donnée personnelle en clair. Mesuré : pedido f6bd398a-… recibido de a***@tienda.mx por $424.00.
utils, le tiroir à outils. Mascara.correo a masqué cette adresse e-mail. N'y va jamais : quelque chose qui sait ce qu'est une commande. S'il le sait, sa place est dans un autre paquet.
Quel chemin suit une commande ?
Vers l'intérieur, de la porte au garde-manger ; et par le raccourci quand il n'y a rien à coordonner.
POST /v1/pedidos GET /v1/pedidos/{id}
│ │
▼ ▼
api (mesero) revisa la comanda api (mesero)
│ │
▼ │ el atajo: lo atiende
facade (jefe de cocina) │ un solo servicio
├──► client (proveedor) ¿hay? │
▼ ▼
service (cocinero) las reglas ◄──────────────┘
│
▼
repository (despensa) guarda la fichaAu retour, la fiche est mise au propre et le ticket sort.
Quand faut-il la facade, et quand non ?
Oui, quand elle coordonne deux services ou clients ou plus. Non, quand sa méthode ne fait qu'en appeler une autre.
Vendredi, 14:10. Le petit resto d'en face.
Lucía a commandé le menu du jour. Iván, seulement une eau d'hibiscus. Le serveur a laissé le bon du menu sur le comptoir de la cuisine, et une femme l'a lu à voix haute : la soupe d'un côté, le plat mijoté de l'autre, et qu'ils sortent ensemble. L'eau, il l'a demandée directement à celui qui la servait.
— Voilà, a dit Lucía. Pour le menu, deux personnes interviennent, et quelqu'un doit dire dans quel ordre. Pour l'eau, non.
Dans le modèle, créer une commande, c'est le menu du jour. Le fournisseur et le cuisinier interviennent, dans cet ordre :
public PedidoResponse crear(CrearPedidoRequest comanda) {
List<LineaCotizada> cotizadas = new ArrayList<>();
for (CrearPedidoRequest.Linea linea : comanda.lineas()) {
InventarioClient.Producto producto = inventario.consultar(linea.sku())
.orElseThrow(() -> new PedidosException(CodigoError.PRODUCTO_NO_EXISTE,
"No hay un producto con el sku " + linea.sku()));
cotizadas.add(new LineaCotizada(linea.sku(), linea.cantidad(), producto.existencias(),
new Dinero(producto.precioCentavos())));
}
PedidoEntity pedido = pedidos.crear(new Correo(comanda.correo()), cotizadas);
return mapper.aResponse(pedido);
}Il demande, transmet et livre. Il ne calcule ni ne décide : ça, c'est le cuisinier. N'y va jamais : un calcul, une règle métier, une requête directe à la base, ni une méthode qui ne fait que passer l'appel à un seul service.
Consulter une commande, c'est l'eau. Un seul service s'en occupe, et le serveur va directement le voir :
@GetMapping("/{id}")
public PedidoResponse buscar(@PathVariable UUID id) {
return mapper.aResponse(service.buscar(id));
}Que coûte une facade de trop ? Un fichier de plus à chaque changement : les quatre d'Iván. Et dans le modèle, aucun test ne la dénonce, parce que les flèches restent correctes. Ça se décide en lisant : combien d'acteurs cette méthode coordonne-t-elle ?
Le lundi, Iván a supprimé cinq méthodes. La facade en a gardé une.
Quelles sont les trois règles ?
Chacun à sa place ; les flèches ne vont que vers l'intérieur ; et ce qui entre, ce qui se garde et ce qui sort sont des choses différentes.
- Chacun à sa place. Si tu ne sais pas où va une ligne, demande-toi de qui c'est le travail.
- Les flèches ne vont que vers l'intérieur.
api → facade → service → repositoryouclient. Le cuisinier n'appelle jamais le serveur. - Ce qui entre, ce qui se garde et ce qui sort sont des choses différentes.
request,entityetresponse, même s'ils se ressemblent aujourd'hui.
La troisième nous a mordus en testant le modèle. Sur macOS, les 71 tests de ce moment-là passaient. Sur Linux, un a échoué : la commande qui venait d'être créée disait "creado_en":"2026-11-17T21:30:32.024605370Z", et la même commande, consultée juste après, "2026-11-17T21:30:32.024605Z". Ce qui était sorti et ce qui avait été gardé n'étaient plus la même chose : la base avait gardé moins de décimales. La correction a été une règle du cuisinier, couper l'heure à la milliseconde, avec son test. C'est pour ça qu'aujourd'hui il y en a 72.
Comment savoir que les flèches pointent vers l'intérieur ?
Parce qu'un test lit les classes compilées et échoue quand l'une d'elles pointe vers l'extérieur. Et parce qu'un script vérifie que ce test sait échouer.
Pour Java, les classes d'un même projet peuvent s'importer entre elles. Si le cuisinier importe le serveur, ça compile. La règle, c'est CapasTest qui la surveille, écrit avec ArchUnit, une bibliothèque « for checking the architecture of your Java code » qui travaille en « analyzing given Java bytecode » [12] : elle examine le compilé, pas le texte. Elle comprend Java 25 depuis sa version 1.4.1 [13] ; le modèle utilise la 1.5.1.
.whereLayer("api").mayNotBeAccessedByAnyLayer()
.whereLayer("facade").mayOnlyBeAccessedByLayers("api")
.whereLayer("service").mayOnlyBeAccessedByLayers("api", "facade")
.whereLayer("repository").mayOnlyBeAccessedByLayers("service")
.whereLayer("client").mayOnlyBeAccessedByLayers("facade", "service")Mais un test qui passe toujours ne démontre rien. herramientas/probar-frontera.sh travaille sur une copie temporaire et lance CapasTest deux fois :
- Contrôle, avec le projet tel quel. Il doit tourner et passer. Sinon, l'expérience est mal montée, ou ton projet porte déjà une flèche vers l'extérieur, et le script s'arrête en rouge.
- Violation. On plante dans
PedidoServiceune méthode qui reçoit unPedidoController. Ça doit compiler, etCapasTestdoit échouer, sur une seule règle et pour la raison exacte.
Voici la sortie réelle :
1/2 control: el proyecto tal como está; el cocinero (service) no conoce al mesero (api)
✅ compiló y CapasTest pasó: 4 reglas, 0 fallas
2/2 violación: se siembra en PedidoService un método que recibe un PedidoController
✅ compiló sin una queja: para Java, que el cocinero conozca al mesero no es un error
Method <mx.habil.pedidos.service.PedidoService.avisar(mx.habil.pedidos.api.PedidoController)> has parameter of type <mx.habil.pedidos.api.PedidoController>
✅ CapasTest falló en una sola regla, lasFlechasSoloVanHaciaAdentro: las flechas solo van hacia adentro
✅ frontera: se sostieneNous l'avons cassé de sept façons, et les sept sont sorties en rouge. Trois en disent long : avec la règle effacée de CapasTest, ❌ PASÓ ; avec une violation qui ne compile pas, il dit que ça « no demuestra la frontera » ; avec Java 21 au lieu de 25, il s'arrête au contrôle.
Quelles sont cinq erreurs fréquentes ?
Les cinq viennent de la même chose : un rôle qui fait le travail d'un autre.
1. Le serveur qui cuisine
Une règle métier dans le contrôleur.
Ça marche, et ça se remarque après : pour tester la règle, il faut démarrer la partie web. Le test du contrôleur du modèle utilise @WebMvcTest, qui laisse de côté les autres composants : « Regular @Component and @ConfigurationProperties beans are not scanned » [22]. Celui du service tourne avec Java, et rien de plus.
2. Le chef de cuisine qui ne fait que passer l'assiette
Une facade dont la méthode ne fait qu'en appeler une autre.
C'est celle d'Iván. Le test d'architecture ne la signale pas : les flèches sont correctes. C'est le compte qui la trahit : combien de services ou de clients chaque méthode coordonne-t-elle ?
3. Livrer la fiche d'archive
Le contrôleur renvoie l'entity.
Ça compile, et ça répond trop. Mesuré dans le modèle, en changeant une seule méthode : sur 72 tests, 3 échouent. L'un le dit sans détour :
Expected no value at JSON path "$.correo" but found: 'ana@tienda.mx'L'adresse e-mail du client est sortie dans une réponse qui n'aurait jamais dû la porter. L'un des trois est CapasTest : il demande si une classe de api dépend d'une entity, pas quel type renvoie une méthode. C'est pour ça qu'il passe aussi au rouge si la fiche est cachée dans un List<PedidoEntity> ou dans un ResponseEntity<PedidoEntity> ; mesuré avec les deux.
4. Appeler le fournisseur sans délai maximal
Si le fournisseur se bloque, ton API se bloque avec lui.
Dans le modèle, le délai maximal tient en une ligne de application.yml [8]. Mesuré : sans cette ligne, le test qui attend un 504 passe au rouge. Et attention à ce qu'on retente : un « n'existe pas » du fournisseur est une réponse. Le modèle ne répète que face à une erreur réseau, et il peut le faire parce que la consultation est un GET : demander deux fois combien il y a de tasses ne change rien. Une écriture, comme encaisser un paiement, ne se retente pas ainsi : il faut d'abord la rendre idempotente, c'est-à-dire que la répéter donne la même chose que la faire une fois.
5. Copier les import d'un vieux tutoriel
Spring Boot 4 utilise Jackson 3 d'office, et ses classes ont changé de paquet.
Jackson, c'est la bibliothèque qui convertit des objets en JSON. Dans Spring Boot 4, la version 3 est « the preferred and default library » [10] ; la 2 reste de façon temporaire, pour migrer, et le modèle ne l'utilise pas. Et le guide de migration le signale : les paquets passent de com.fasterxml.jackson à tools.jackson, avec une exception, les annotations, qui restent dans com.fasterxml.jackson.annotation [11]. Mesuré dans le modèle, avec un import d'avant :
package com.fasterxml.jackson.databind does not exist| Erreur | Ce qui la trahit | Source |
|---|---|---|
| 1. Le serveur qui cuisine | Un if sur une donnée de la commande dans api | [2][22] |
| 2. La facade qui ne fait que passer l'assiette | Une méthode qui ne fait qu'en appeler une autre | règle du modèle |
| 3. Livrer la fiche | Une donnée de trop dans le JSON | mesure |
| 4. Sans délai maximal | Une réponse lente qui finit par arriver | [8][9] |
5. import de vieux tutoriel | package … does not exist | [10][11] |
Exercice : peux-tu faire que le cuisinier appelle le serveur ?
Tu vas planter une flèche vers l'extérieur, voir que Java l'accepte et voir comment le test et le script te préviennent.
Il te faut Java 25 (java -version), Git, bash et curl ; environ 25 minutes. Pas Maven : le projet l'apporte.
- Sur Linux et sur macOS, installe Java avec SDKMAN [23]. Sur Linux, il faut d'abord
curl,zipetunzip(mesuré sur Ubuntu 24.04, la base de Linux Mint 22 [28]) :
sudo apt install curl zip unzip
curl -s "https://get.sdkman.io" | bashOuvre un autre terminal, entre dans le dossier du modèle (celui de l'étape 1) et lance sdk env install. Ouvre encore un terminal (dans celui où tu as installé, java est encore introuvable ; mesuré) et, dans ce dossier, lance sdk env. La leçon 1 du cours de Java l'explique pas à pas. - Sur Windows, utilise WSL.
Étape 1. Clone et vérifie que tout est au vert.
git clone https://github.com/HabilMX/estructura-java-spring-boot
cd estructura-java-spring-boot
./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: 72, 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 cuisinier, PedidoService, une méthode qui reçoit le serveur, PedidoController. Note : est-ce que ça compile ? Que dit CapasTest ? Et le script de la frontière ?
Étape 3. Plante la flèche. La première ligne enlève la dernière accolade de la classe et laisse une copie .bak ; la seconde ajoute la méthode et ferme la classe. Elles marchent pareil sur Linux et sur macOS.
sed -i.bak '$d' src/main/java/mx/habil/pedidos/service/PedidoService.java
printf ' public void avisar(mx.habil.pedidos.api.PedidoController mesero) {\n }\n}\n' \
>> src/main/java/mx/habil/pedidos/service/PedidoService.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.service.PedidoService.avisar(mx.habil.pedidos.api.PedidoController)> has parameter of type <mx.habil.pedidos.api.PedidoController> in (PedidoService.java:0)Étape 4. Interroge le script.
bash herramientas/probar-frontera.shIl passe au rouge, sans arriver à la deuxième étape :
❌ 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é. L'exercice a changé un fichier. Avant de le remettre, regarde ce qui a changé dedans :
git diff -- src/main/java/mx/habil/pedidos/service/PedidoService.javaTu dois voir deux lignes nouvelles : la méthode avisar et son accolade. Si tu vois autre chose, c'est à toi : mets-le de côté 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 [24] :
git restore src/main/java/mx/habil/pedidos/service/PedidoService.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/service/PedidoService.java.bakGarde-la jusqu'à être sûr de ne pas en avoir besoin. Ensuite, efface-la avec rm -i, qui demande avant. N'utilise pas une commande qui nettoie tout le dossier : elle emporterait aussi tes notes.
Comment savoir que tu 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 PedidoService.java se termine par une seule accolade }.
Pour aller plus loin (facultatif) : fais que le serveur livre la fiche. Dans PedidoController, change la méthode buscar pour qu'elle renvoie mx.habil.pedidos.model.entity.PedidoEntity et retourne service.buscar(id) sans passer par le mapper. Avant, prédis : est-ce que ça compile ? Combien de tests échouent ? Réponse : ça compile, et ./mvnw -q test se termine avec Tests run: 72, Failures: 3 (mesuré). Remets tout comme à l'étape 5 : git diff de ce fichier, et git restore avec son chemin.
À retenir
Trois questions à poser à ton dépôt cette semaine.
- Combien de méthodes de ta
facadene font qu'en appeler une autre ? Chacune, c'est un fichier de plus au prochain changement. - Un contrôleur renvoie-t-il une
entity? Si oui, quel champ de la table sort sans que personne l'ait demandé ? - Qu'est-ce qui te prévient si demain un service importe un contrôleur ? Si la réponse est « la revue de code », ça dépend de quelqu'un qui le voie.
Et ensuite ?
Le restaurant ne dépend pas de la marque de la cuisinière.
Deux semaines plus tard, on a passé à Iván une autre API de commandes. Il a ouvert le projet et a reconnu les dossiers : api, facade, service, repository. Il a cherché @RestController pour commencer par le serveur.
Il n'y en avait aucun.
La classe qui démarre l'application n'était pas là non plus. Pas un seul import de Spring. Et pourtant, les couches étaient les mêmes et les flèches pointaient vers l'intérieur. Le dimanche 6 décembre, dans l'épisode 6 : même restaurant, une autre cuisine, plus rapide. Les mêmes couches en Quarkus, ce qui change dans chaque paquet et à quel point c'est rapide, mesuré.
Le modèle et le cours
- Modèle : github.com/HabilMX/estructura-java-spring-boot. Il s'utilise comme modèle GitHub ou se clone [26]. Le README explique chaque paquet avec son « jamais », le chemin d'une commande, 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, un serveur minimal que le JDK apporte déjà [25]. La base est H2, en mémoire [7] : le plus simple qui tourne du premier coup ; les données s'effacent à l'arrêt. La santé répond sur/actuator/health, et d'Actuator rien d'autre n'est publié [21]. - Versions : Java 25, la version à support long (LTS) en vigueur [20], avec Temurin 25.0.5+8. Spring Boot 4.1.2, celle en vigueur le 17 novembre [19], qui accepte de Java 17 à Java 27 [18] ; le modèle reste sur la 25 et ne laisse pas construire avec une autre. Maven 3.9.16, par le Wrapper [15]. ArchUnit 1.5.1 [13]. Testé sur macOS arm64 (aussi avec le
/bin/bashdu système) et sur Linux arm64 (conteneurubuntu:24.04). Linux x86-64 n'a pas encore été testé. La CI est écrite pour Ubuntu et macOS avec Temurin 25, à chaque changement et chaque lundi ; si le dépôt public passe 60 jours sans activité, GitHub désactive l'exécution du lundi [27]. - 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 · Leçon 3, Records, enums et types scellés · Leçon 6, Projet avec Maven.
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 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 17 novembre 2026. Les citations en anglais sont reproduites telles quelles.
Références
- Spring Boot 4.1.2, « Structuring Your Code ». https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html
- Spring Framework, « Classpath Scanning and Managed Components » :
@Componentet les annotations de stéréotype. https://docs.spring.io/spring-framework/reference/core/beans/classpath-scanning.html - Spring Framework, « Error Responses ». https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html
- 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
- Spring Framework, « Validation » (Spring MVC, méthodes de contrôleur). https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-controller/ann-validation.html
- Eclipse Foundation, « Jakarta Validation 3.1 ». https://jakarta.ee/specifications/bean-validation/3.1/
- Spring Boot 4.1.2, « SQL Databases » : « Embedded Database Support » et les dépôts Spring Data. https://docs.spring.io/spring-boot/reference/data/sql.html
- Spring Boot 4.1.2, « REST Clients » :
spring.http.clients.connect-timeoutetread-timeout. https://docs.spring.io/spring-boot/reference/io/rest-client.html - Spring Framework, « Resilience Features ». https://docs.spring.io/spring-framework/reference/core/resilience.html
- Spring Boot 4.1.2, « JSON » (« Jackson 3 is the preferred and default library »). https://docs.spring.io/spring-boot/reference/features/json.html
- Spring Boot, « Spring Boot 4.0 Migration Guide » : « Upgrading Jackson ». https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
- ArchUnit, « ArchUnit User Guide » : « Introduction » et « Layer Checks ». https://www.archunit.org/userguide/html/000_Index.html
- TNG, « ArchUnit », versions 1.4.1 (« Support Java 25 ») et 1.5.1, GitHub. https://github.com/TNG/ArchUnit/releases
- Apache Maven, « Introduction to the Standard Directory Layout ». https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html
- Apache Maven, « Maven Wrapper ». https://maven.apache.org/tools/wrapper/
- Oracle, « Record Classes », Java Language Updates, Java SE 25. https://docs.oracle.com/en/java/javase/25/language/records.html
- Eclipse Foundation, « Jakarta Persistence 3.2 », section « The Entity Class ». https://jakarta.ee/specifications/persistence/3.2/jakarta-persistence-spec-3.2
- Spring Boot 4.1.2, « System Requirements ». https://docs.spring.io/spring-boot/system-requirements.html
- Spring, versions de Spring Boot (API de spring.io) : 4.1.2, celle en vigueur. https://api.spring.io/projects/spring-boot/releases
- Eclipse Adoptium, « Support » (« Java 25 (LTS) »). https://adoptium.net/support/
- Spring Boot 4.1.2, « Endpoints » (Actuator). https://docs.spring.io/spring-boot/reference/actuator/endpoints.html
- Spring Boot 4.1.2, « Testing Spring Boot Applications » :
@WebMvcTest. https://docs.spring.io/spring-boot/reference/testing/spring-boot-applications.html - SDKMAN, « Usage » :
sdk env. https://sdkman.io/usage/ - Git, « git-restore » (« Restore specified paths in the working tree »). https://git-scm.com/docs/git-restore
- Oracle, « The jwebserver Command », Java SE 25. https://docs.oracle.com/en/java/javase/25/docs/specs/man/jwebserver.html
- GitHub Docs, « Creating a template repository ». https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository
- GitHub Docs, « Disabling and enabling a workflow ». https://docs.github.com/en/actions/how-tos/manage-workflow-runs/disable-and-enable-workflows
- Linux Mint, « Linux Mint 22 Release Notes » (« Linux Mint 22.x is based on Ubuntu 24.04 »), linuxmint.com. https://www.linuxmint.com/rel_wilma.php
Votre activité fait face à ces défis ?
Vous préférez l'e-mail ? Écrivez-nous à hola@habil.mx