La estructura de un proyecto (5): la capa que no hacía nada
Por Dorian Chávez · cofundador y Chief Executive Officer de Hábil ·
Cuatro capas y una facade que solo pasa la llamada. Qué va en cada paquete de una API con Spring Boot, cuándo sobra la facade y una plantilla que lo vigila.
La estructura de un proyecto · entrega 5 de 7 · Java con Spring Boot
Escenario: los personajes y la historia son inventados. Los datos técnicos y las citas llevan su fuente al final.
En 1 minuto
- Spring Boot no exige ninguna forma de acomodar el código [1]. Las capas son una decisión; aquí va la de la plantilla, con su porqué.
- Cada paquete es un papel de un restaurante:
apies el mesero,serviceel cocinero,repositoryla despensa. Y cada papel tiene algo que nunca hace. - La
facade, el jefe de cocina, se justifica cuando coordina a dos o más. Si su método solo llama a otro, sobra. - Para Java, que el cocinero conozca al mesero no es un error: compila. Lo detecta una prueba de arquitectura [12].
- Te llevas una plantilla que corre a la primera, con un guion que demuestra esa frontera poniéndose rojo cuando debe.
- Para el lunes: abre tu
facadey cuenta cuántos métodos solo llaman a otro.
En este artículo
- ¿Qué pasó el jueves a las 16:40?
- ¿Qué va en cada paquete?
- ¿Cuándo sí y cuándo no la facade?
- ¿Cuáles son las tres reglas?
- ¿Cuáles son cinco errores frecuentes?
- Ejercicio: ¿puedes hacer que el cocinero llame al mesero?
- Para llevar
- ¿Qué sigue?
- La plantilla y el curso
- ¿Qué hace Hábil?
- Referencias
¿Qué pasó el jueves a las 16:40?
Iván agregó un campo a una respuesta, tocó cuatro archivos y encontró una capa que no hacía nada.
Jueves, 16:05. Piso tres.
Un mes después del alias. Primera API en Java, con Spring Boot: los pedidos de una tienda. El encargo cabía en un renglón: «Que la consulta de un pedido diga también cuándo se creó».
El proyecto lo había dejado alguien más. Cuatro carpetas con nombre de capa:
src/main/java/…/pedidos/
api/
facade/
service/
repository/El dato ya estaba en la tabla. Para que llegara al JSON, Iván tocó cuatro archivos, uno por carpeta. En tres copió el campo de una clase a otra. En el cuarto, la facade, se detuvo:
public PedidoResponse buscar(UUID id) {
return service.buscar(id);
}Un método que solo llamaba a otro. Recibía lo mismo y devolvía lo mismo. Revisó los demás métodos de la clase: eran seis, y cinco hacían eso.
Jueves, 16:40.
Compiló. Las pruebas pasaron. Antes de subir el cambio, le escribió a Lucía.
—Cuatro archivos para mover un dato. Y una capa no hace nada: llama a la que sigue y ya. ¿La quito?
—¿A cuántos llama ese método? —contestó ella.
—A uno. Al servicio.
—¿Y el de crear un pedido?
Iván lo abrió. Ese era distinto: primero le preguntaba el precio a otro sistema, y después llamaba al servicio.
—A dos.
—Entonces en uno sobra el jefe de cocina, y en el otro no.
—¿Qué jefe de cocina?
—Mañana comemos en la fonda de enfrente. Fíjate quién hace qué.
Iván miró las cuatro carpetas. Había creído que eran cuatro pasos obligatorios. Eran cuatro oficios.
¿Qué va en cada paquete?
Lo que le toca a un papel de un restaurante, y nada más. Las capas no las pide Spring Boot: son una decisión.
La documentación de Spring Boot lo dice de entrada: «Spring Boot does not require any specific code layout to work» [1]. Su propio ejemplo ni siquiera acomoda por capas: pone una carpeta para clientes y otra para órdenes [1]. Lo que sí recomienda es dónde va la clase que arranca: «in a root package above other classes» [1]. De ese paquete hacia abajo busca Spring los componentes y las entidades.
¿De dónde salen entonces api, service y repository? De una costumbre que Spring lleva en sus anotaciones: @Controller, @Service y @Repository existen para las capas «persistence, service, and presentation» [2]. En Hábil es práctica de la casa: un paquete por papel, y las dependencias en un solo sentido. No es la única forma correcta. Es una que cabe en una comida.
La plantilla de esta entrega, estructura-java-spring-boot, es la API de pedidos de una tienda. Su paquete raíz es mx.habil.pedidos: el dominio al revés y el nombre de la aplicación [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 y src/test son el acomodo estándar de Maven, la herramienta que construye el proyecto: sirve para que quien conoce un proyecto pueda «immediately feel at home in another» [14]. mvnw es el Maven Wrapper: baja la versión de Maven que el proyecto declara, y nadie la instala a mano [15].
Vamos papel por papel. Cada uno trae su ejemplo de la plantilla y una línea: lo que nunca va ahí.
¿Quiénes atienden?
api, el mesero. Recibe la comanda, revisa que venga bien llenada y la pasa. No cocina.
@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);
}Todo lo que es HTTP vive aquí: la ruta, el verbo, el 201. @Valid es la revisión: si la comanda viene mal llenada, Spring lanza MethodArgumentNotValidException [5] y la cocina ni se entera. Nunca va aquí: una regla del negocio. Un if sobre un dato del pedido es del cocinero.
service, el cocinero. Aquí viven las reglas. La plantilla tiene dos: no se acepta un pedido si falta una pieza, y el total es precio por cantidad.
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());Nunca va aquí: HTTP ni JSON. El cocinero no sabe si el pedido llegó por una app o por teléfono; por eso sus pruebas corren sin servidor y sin base de datos.
repository, la despensa. Guarda y trae.
public interface PedidoRepository extends JpaRepository<PedidoEntity, UUID> {
}Es toda la interfaz. Spring Data se encarga de «creating Repository implementations directly from interfaces» [7]. Nunca va aquí: una decisión. Si un pedido se puede guardar, lo dice el cocinero.
client, el proveedor de afuera. Otro sistema, en otra máquina. En la plantilla es el inventario: cuántas piezas hay y a cuánto. Se le llama con dos cuidados. Un tiempo límite: application.yml declara un segundo para conectar y dos para leer [8]. Y un reintento, solo ante un error de red de los que Spring llama ResourceAccessException; un 404 del proveedor es una respuesta y no se repite. Spring Framework 7 ya trae el reintento en su núcleo [9]. Dos reintentos son tres llamadas: «total attempts = 1 initial attempt + maxRetries attempts» [9]. Nunca va aquí: una regla del pedido. Ni una llamada sin tiempo límite.
facade, el jefe de cocina. Coordina. Es la pregunta de Iván, y tiene su sección.
¿Qué papeles pasan de mano en mano?
request es la comanda, response el ticket y entity la ficha del archivo. Tres papeles, aunque digan casi lo mismo.
public record CrearPedidoRequest(
@NotBlank @Email @Size(max = 254) String correo,
@NotEmpty @Size(max = 20) List<@Valid @NotNull Linea> lineas) {La comanda y el ticket son record: clases que solo cargan datos, con sus campos finales [16]. Las anotaciones son de Jakarta Validation [6]. La comanda no trae precio: el precio lo pone el proveedor, no el cliente. El ticket no trae el correo: nadie lo pidió. La ficha, PedidoEntity, tiene la forma de la tabla, y es una clase normal porque la especificación de JPA dice que un record «may not be designated as an entity» [17]. Nunca: que la ficha salga por la puerta. El mesero entrega el ticket.
¿Y los demás paquetes?
vo, la medida exacta. vo quiere decir value object, objeto de valor: se reconoce por lo que vale, no por un id; dos Dinero de 100 centavos son la misma cantidad. Dinero no es un long suelto: es una cantidad en centavos que nunca es negativa. Si existe, ya es válido, y nadie vuelve a revisarlo. Lo mismo Correo. Nunca va aquí: algo de Spring o de otra capa.
mapper, el que pasa en limpio. Copia de la ficha al ticket, campo por campo. Nunca va aquí: un if que decida algo.
config, la instalación del local. El reloj, el teléfono para llamar al proveedor, cuántas veces se reintenta. Se arma una vez, al abrir. Nunca va aquí: reglas ni rutas.
exception, el libro de quejas. Todo lo que puede salir mal tiene un código en un catálogo, y un solo lugar arma la respuesta. La forma no es nuestra: es Problem Details, el RFC 9457, que existe «to avoid the need to define new error response formats for HTTP APIs» [4], y Spring ya lo trae [3]. Medido en la plantilla, pidiendo cuatro tazas cuando hay tres:
{"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"}Nunca va aquí: un formato de error propio.
observability, las cámaras y la bitácora. Cada petición recibe un número, que sale en cada línea de la bitácora y regresa al cliente en X-Request-ID. Nunca va aquí: un dato personal en claro. Medido: pedido f6bd398a-… recibido de a***@tienda.mx por $424.00.
utils, el cajón de herramientas. Mascara.correo tapó ese correo. Nunca va aquí: algo que sepa qué es un pedido. Si lo sabe, su lugar es otro paquete.
¿Qué camino sigue un pedido?
Hacia adentro, de la puerta a la despensa; y por el atajo cuando no hay nada que coordinar.
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 fichaDe regreso, la ficha se pasa en limpio y sale el ticket.
¿Cuándo sí y cuándo no la facade?
Sí, cuando coordina a dos o más servicios o clientes. No, cuando su método solo llama a otro.
Viernes, 14:10. La fonda de enfrente.
Lucía pidió el menú del día. Iván, solo un agua de jamaica. El mesero dejó la comanda del menú en la barra de la cocina, y una mujer la leyó en voz alta: la sopa a un lado, el guisado al otro, que salieran juntos. El agua la pidió directo a quien la servía.
—Ahí está —dijo Lucía—. Para el menú intervienen dos, y alguien tiene que decir el orden. Para el agua, no.
En la plantilla, crear un pedido es el menú del día. Intervienen el proveedor y el cocinero, en ese orden:
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);
}Pregunta, pasa y entrega. No calcula ni decide: eso es del cocinero. Nunca va aquí: un cálculo, una regla del negocio, una consulta directa a la base, ni un método que solo le pase la llamada a un solo servicio.
Consultar un pedido es el agua. Lo atiende un solo servicio, y el mesero va directo:
@GetMapping("/{id}")
public PedidoResponse buscar(@PathVariable UUID id) {
return mapper.aResponse(service.buscar(id));
}¿Qué cuesta una facade que sobra? Un archivo más en cada cambio: los cuatro de Iván. Y en la plantilla ninguna prueba la delata, porque las flechas quedan bien. Se decide leyendo: ¿a cuántos coordina este método?
El lunes, Iván borró cinco métodos. La facade se quedó con uno.
¿Cuáles son las tres reglas?
Cada quien en lo suyo; las flechas solo hacia adentro; y lo que entra, lo que se guarda y lo que sale son cosas distintas.
- Cada quien en lo suyo. Si no sabes dónde va una línea, pregunta de quién es el trabajo.
- Las flechas solo hacia adentro.
api → facade → service → repositoryoclient. El cocinero nunca llama al mesero. - Lo que entra, lo que se guarda y lo que sale son cosas distintas.
request,entityyresponse, aunque hoy se parezcan.
La tercera nos mordió al probar la plantilla. En macOS, las 71 pruebas de ese momento pasaban. En Linux, una falló: el pedido recién creado decía "creado_en":"2026-11-17T21:30:32.024605370Z", y el mismo pedido, consultado enseguida, "2026-11-17T21:30:32.024605Z". Lo que salió y lo que se guardó ya no eran lo mismo: la base había guardado menos decimales. El arreglo fue una regla del cocinero, cortar la hora al milisegundo, con su prueba. Por eso hoy son 72.
¿Cómo sé que las flechas apuntan hacia adentro?
Porque una prueba lee las clases compiladas y falla cuando una apunta hacia afuera. Y porque un guion comprueba que esa prueba sabe fallar.
Para Java, las clases de un mismo proyecto pueden importarse entre sí. Si el cocinero importa al mesero, compila. La regla la vigila CapasTest, escrita con ArchUnit, una biblioteca «for checking the architecture of your Java code» que trabaja «analyzing given Java bytecode» [12]: revisa lo compilado, no el texto. Entiende Java 25 desde su versión 1.4.1 [13]; la plantilla usa 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")Pero una prueba que siempre pasa no demuestra nada. herramientas/probar-frontera.sh trabaja en una copia temporal y corre CapasTest dos veces:
- Control, con el proyecto tal como está. Tiene que correr y pasar. Si no, el experimento está mal montado, o tu proyecto ya trae una flecha hacia afuera, y el guion se detiene en rojo.
- Violación. Se siembra en
PedidoServiceun método que recibe unPedidoController. Tiene que compilar, yCapasTesttiene que fallar, en una sola regla y por la razón exacta.
Ésta es la salida real:
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 sostieneLo rompimos de siete maneras, y las siete salieron en rojo. Tres dicen mucho: con la regla borrada de CapasTest, ❌ PASÓ; con una violación que no compila, dice que eso «no demuestra la frontera»; con Java 21 en lugar de 25, se detiene en el control.
¿Cuáles son cinco errores frecuentes?
Los cinco salen de lo mismo: un papel haciendo el trabajo de otro.
1. El mesero que cocina
Una regla del negocio en el controlador.
Funciona, y se nota después: para probar la regla hay que levantar la parte web. La prueba del controlador de la plantilla usa @WebMvcTest, que deja fuera a los demás componentes: «Regular @Component and @ConfigurationProperties beans are not scanned» [22]. La del servicio corre con Java y nada más.
2. El jefe de cocina que solo pasa el plato
Una facade cuyo método solo llama a otro.
Es el de Iván. La prueba de arquitectura no lo marca: las flechas están bien. Lo delata el conteo: ¿a cuántos servicios o clientes coordina cada método?
3. Entregar la ficha del archivo
El controlador devuelve la entity.
Compila, y contesta de más. Medido en la plantilla, cambiando un solo método: de 72 pruebas fallan 3. Una lo dice sin rodeos:
Expected no value at JSON path "$.correo" but found: 'ana@tienda.mx'El correo del cliente salió en una respuesta que nunca debió llevarlo. Una de las tres es CapasTest: pregunta si alguna clase de api depende de una entity, no qué tipo devuelve un método. Por eso también se pone roja si la ficha va escondida en un List<PedidoEntity> o en un ResponseEntity<PedidoEntity>; medido con los dos.
4. Llamar al proveedor sin tiempo límite
Si el proveedor se cuelga, tu API se cuelga con él.
En la plantilla, el tiempo límite es un renglón de application.yml [8]. Medido: sin ese renglón, la prueba que espera un 504 se pone roja. Y ojo con lo que se reintenta: un «no existe» del proveedor es una respuesta. La plantilla solo repite ante un error de red, y puede hacerlo porque la consulta es un GET: preguntar dos veces cuántas tazas hay no cambia nada. Una escritura, como cobrar, no se reintenta así: primero hay que hacerla idempotente, que repetirla dé lo mismo que hacerla una vez.
5. Copiar los import de un tutorial viejo
Spring Boot 4 usa Jackson 3 de entrada, y sus clases cambiaron de paquete.
Jackson es la biblioteca que convierte objetos en JSON. En Spring Boot 4, la versión 3 es «the preferred and default library» [10]; la 2 sigue de forma temporal, para migrar, y la plantilla no la usa. y la guía de migración lo avisa: los paquetes pasan de com.fasterxml.jackson a tools.jackson, con una excepción, las anotaciones, que siguen en com.fasterxml.jackson.annotation [11]. Medido en la plantilla, con un import de los de antes:
package com.fasterxml.jackson.databind does not exist| Error | Lo que lo delata | Fuente |
|---|---|---|
| 1. El mesero que cocina | Un if sobre un dato del pedido en api | [2][22] |
| 2. La facade que solo pasa el plato | Un método que solo llama a otro | regla de la plantilla |
| 3. Entregar la ficha | Un dato de más en el JSON | medición |
| 4. Sin tiempo límite | Una respuesta lenta que sí llega | [8][9] |
5. import de tutorial viejo | package … does not exist | [10][11] |
Ejercicio: ¿puedes hacer que el cocinero llame al mesero?
Vas a sembrar una flecha hacia afuera, ver que Java la acepta y ver cómo la prueba y el guion te avisan.
Necesitas Java 25 (java -version), Git, bash y curl; unos 25 minutos. Maven no: lo trae el proyecto.
- En Linux y en macOS, instala Java con SDKMAN [23]. En Linux hacen falta antes
curl,zipyunzip(medido en Ubuntu 24.04, la base de Linux Mint 22 [28]):
sudo apt install curl zip unzip
curl -s "https://get.sdkman.io" | bashAbre otra terminal, entra a la carpeta de la plantilla (la del paso 1) y corre sdk env install. Abre una terminal más (en la que instaló, java todavía no se encuentra; medido) y, en esa carpeta, corre sdk env. La lección 1 del curso de Java lo cuenta paso a paso. - En Windows, usa WSL.
Paso 1. Clona y comprueba que todo está en verde.
git clone https://github.com/HabilMX/estructura-java-spring-boot
cd estructura-java-spring-boot
./mvnw verify
bash herramientas/probar-frontera.shLa primera vez tarda: baja Maven y las bibliotecas. Debes ver Tests run: 72, Failures: 0, Errors: 0, Skipped: 0, luego BUILD SUCCESS y, al final del guion, ✅ frontera: se sostiene.
Usa este clon solo para practicar. Así, todo cambio que veas en él es del ejercicio.
Paso 2. Predice antes de tocar. Vas a agregarle al cocinero, PedidoService, un método que recibe al mesero, PedidoController. Anota: ¿compila? ¿Qué dice CapasTest? ¿Y el guion de la frontera?
Paso 3. Siembra la flecha. La primera línea quita la última llave de la clase y deja una copia .bak; la segunda agrega el método y cierra la clase. Sirven igual en Linux y en 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 termina sin decir nada: compiló. La prueba, no. Entre muchas líneas, las que importan:
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)Paso 4. Pregúntale al guion.
bash herramientas/probar-frontera.shSe pone rojo, sin llegar al segundo paso:
❌ el control NO pasó: tu proyecto, tal como está, ya rompe una regla de CapasTest:Ése es el control trabajando: no puede demostrar que la prueba sabe fallar si tu proyecto ya la tiene fallando.
Paso 5. Regresa solo lo que tocaste. El ejercicio cambió un archivo. Antes de regresarlo, mira qué cambió en él:
git diff -- src/main/java/mx/habil/pedidos/service/PedidoService.javaDebes ver dos líneas nuevas: el método avisar y su llave. Si ves algo más, es tuyo: guárdalo antes de seguir. Si solo está lo del ejercicio, regresa ese archivo. git restore solo toca las rutas que le das [24]:
git restore src/main/java/mx/habil/pedidos/service/PedidoService.java
bash herramientas/probar-frontera.sh
git status --shortLa frontera vuelve a verde, y git status enseña lo que queda: la copia que hizo sed.
?? src/main/java/mx/habil/pedidos/service/PedidoService.java.bakConsérvala hasta que estés seguro de que no la necesitas. Luego bórrala con rm -i, que pregunta antes. No uses un comando que limpie toda la carpeta: se llevaría también tus notas.
Cómo sabes que lo hiciste bien: corriste seis veces y viste tres desenlaces. Verde, cuatro veces: las dos del paso 1, test-compile en el paso 3 y la frontera del paso 5. Rojo de la prueba, una vez: Failures: 1 en el paso 3. Y el rojo del guion, «el control NO pasó», en el paso 4. Si en el paso 3 test-compile marca un error, revisa que PedidoService.java termine en una sola llave }.
Para ir más lejos (opcional): haz que el mesero entregue la ficha. En PedidoController, cambia el método buscar para que devuelva mx.habil.pedidos.model.entity.PedidoEntity y regrese service.buscar(id) sin pasar por el mapper. Antes, predice: ¿compila? ¿Cuántas pruebas fallan? Respuesta: compila, y ./mvnw -q test termina con Tests run: 72, Failures: 3 (medido). Regresa igual que en el paso 5: git diff de ese archivo, y git restore con su ruta.
Para llevar
Tres preguntas para hacerle a tu repositorio esta semana.
- ¿Cuántos métodos de tu
facadesolo llaman a otro? Cada uno es un archivo de más en el siguiente cambio. - ¿Algún controlador devuelve una
entity? Si sí, ¿qué campo de la tabla está saliendo sin que nadie lo haya pedido? - ¿Qué te avisa si mañana un servicio importa un controlador? Si la respuesta es «la revisión de código», depende de que alguien lo vea.
¿Qué sigue?
El restaurante no depende de la marca de la estufa.
Dos semanas después, a Iván le pasaron otra API de pedidos. Abrió el proyecto y reconoció las carpetas: api, facade, service, repository. Buscó @RestController para empezar por el mesero.
No había ninguno.
Tampoco estaba la clase que arranca la aplicación. Ni un solo import de Spring. Y aun así, las capas eran las mismas y las flechas apuntaban hacia adentro. El domingo 6 de diciembre, en la entrega 6: mismo restaurante, otra cocina más rápida. Las mismas capas en Quarkus, qué cambia en cada paquete y qué tan rápida es, medida.
La plantilla y el curso
- Plantilla: github.com/HabilMX/estructura-java-spring-boot. Se usa como plantilla de GitHub o se clona [26]. El README explica cada paquete con su «nunca», el camino de un pedido, lo que no trae (autenticación, una base de verdad, contrato OpenAPI), cuándo agregar cada cosa y cómo quitar el ejemplo. El código es MIT; el texto y las explicaciones son CC BY-SA 4.0.
- Para verla trabajar: el README trae los
curl. El proveedor de inventario de ejemplo es una carpeta con dos archivos JSON, servida conjwebserver, un servidor mínimo que ya trae el JDK [25]. La base es H2, en memoria [7]: lo más simple que corre a la primera; los datos se borran al apagar. La salud contesta en/actuator/health, y de Actuator no se publica nada más [21]. - Versiones: Java 25, la versión de soporte largo (LTS) vigente [20], con Temurin 25.0.5+8. Spring Boot 4.1.2, la vigente el 17 de noviembre [19], que acepta de Java 17 a Java 27 [18]; la plantilla se queda en la 25 y no deja construir con otra. Maven 3.9.16, por el Wrapper [15]. ArchUnit 1.5.1 [13]. Se probó en macOS arm64 (también con el
/bin/bashdel sistema) y en Linux arm64 (contenedorubuntu:24.04). Linux x86-64 todavía no se ha probado. El CI está escrito para Ubuntu y macOS con Temurin 25, en cada cambio y cada lunes; si el repositorio público pasa 60 días sin actividad, GitHub apaga la corrida de los lunes [27]. - Curso de Java de Hábil: si los
record, Maven o las pruebas con JUnit son nuevos para ti, empieza ahí: Curso de Java · Lección 3, records · Lección 6, un proyecto con Maven.
Escribo desde lo que vemos todos los días en Hábil, donde construimos sistemas para banca, seguros y empresas en México. Si en tu trabajo o en tu escuela se topan con un repositorio que nadie sabe dónde tocar, platiquemos: habil.mx
¿Qué hace Hábil?
Enseñamos a programar con lo mismo que usamos para construir: código probado, explicado y abierto.
Esta serie nace del mismo lugar que nuestros cursos. El Curso de Java enseña el Java de hoy: tipos que expresan el modelo, pruebas, concurrencia y un programa terminado, empaquetado en un JAR, y lo publicamos abierto, con licencia Creative Commons; su lección 3 cuenta los record y su lección 6 el proyecto con Maven que usa la plantilla de este artículo. Y en el catálogo hay más cursos de programación, gratuitos y con código probado y explicado paso a paso.
Mira el Curso de Java y el catálogo de Cursos de programación.
Si tu equipo hereda un sistema que nadie sabe dónde tocar, o necesita construir uno que se pueda seguir manteniendo, también lo hacemos: mira Construir su sistema a la medida. Pide tu primera conversación, sin costo. En ella revisamos si conviene configurar lo que ya tienen, usar un producto o construir, y qué recibirían en cada caso. Escríbenos por WhatsApp.
Fuentes consultadas el 17 de noviembre de 2026. Las citas en inglés se reproducen tal cual.
Referencias
- 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»:
@Componenty las anotaciones de estereotipo. 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 y S. Dalal, «RFC 9457: Problem Details for HTTP APIs», IETF, julio de 2023. https://www.rfc-editor.org/rfc/rfc9457.html
- Spring Framework, «Validation» (Spring MVC, métodos de controlador). 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» y los repositorios de Spring Data. https://docs.spring.io/spring-boot/reference/data/sql.html
- Spring Boot 4.1.2, «REST Clients»:
spring.http.clients.connect-timeoutyread-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» y «Layer Checks». https://www.archunit.org/userguide/html/000_Index.html
- TNG, «ArchUnit», versiones 1.4.1 («Support Java 25») y 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», apartado «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, versiones de Spring Boot (API de spring.io): 4.1.2, la vigente. 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
¿Su operación tiene estos desafíos?
¿Prefiere correo? Escríbanos a hola@habil.mx