La estructura de un proyecto (6): la cocina que se arma la noche anterior
Por Dorian Chávez · cofundador y Chief Executive Officer de Hábil ·
La misma API de pedidos, de Spring Boot a Quarkus: qué cambia en cada paquete, cuánto tarda en abrir y cuánto pesa, medido, y lo que esa cifra no le dice.
La estructura de un proyecto · entrega 6 de 7 · Quarkus
Escenario: los personajes y la historia son inventados. Los datos técnicos y las citas llevan su fuente al final.
En 1 minuto
- Es el mismo restaurante de la entrega 5:
apies el mesero,serviceel cocinero,repositoryla despensa. Lo que cambia es la cocina: la herramienta de cada papel. - La idea central de Quarkus es hacer «at build-time what traditional frameworks do at runtime» [1]. La cocina se arma la noche anterior, y por eso abre rápido.
- Medido en la plantilla, hasta el primer pedido creado: Spring Boot, 2.2 s y 437 MiB; Quarkus en la JVM (la máquina virtual que ejecuta Java), 1.2 s y 270 MiB; Quarkus compilado a nativo (un ejecutable que no necesita la JVM), 46 ms y 60 MiB.
- Abrir rápido no es cocinar rápido. En el banco de pruebas de la guía oficial, el nativo atiende ~59 % menos peticiones por segundo que la JVM [2]. El nativo se elige por el arranque y la memoria, con la medida en la mano.
- Las flechas siguen apuntando hacia adentro, y la misma prueba de arquitectura se pone roja si alguien las voltea. Hay un error que ninguna prueba de la plantilla ve: lo encuentras con un
grep. - Para el lunes: busca
extends PanacheEntityen tu proyecto. Cada resultado es una ficha del archivo que también hace de despensa.
En este artículo
- ¿Qué pasó el lunes a las 9:12?
- ¿Qué cambia y qué no?
- ¿Qué quiere decir «la noche anterior»?
- ¿Qué cambia en cada paquete?
- ¿Qué tan rápido abre?
- ¿Siguen las flechas hacia adentro?
- ¿Cuáles son cinco errores frecuentes?
- Ejercicio: ¿puedes esconder la ficha en el ticket?
- Para llevar
- ¿Qué sigue?
- La plantilla y el curso
- ¿Qué hace Hábil?
- Referencias
¿Qué pasó el lunes a las 9:12?
Iván vio arrancar una API en 46 milisegundos y quiso pasar todo a nativo. Lucía le hizo dos preguntas.
Lunes, 9:05. Piso tres.
La API de pedidos nueva tenía las carpetas de siempre: api, facade, service. Iván buscó al mesero y encontró PedidoResource. No había @RestController, no había clase con main, y la despensa no estaba donde la esperaba: vivía dentro de model/.
La construyó y la arrancó. La bitácora dijo:
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.Dos puertos. Apuntó la duda y siguió.
Lunes, 9:12.
Lucía pasó por su lugar con el café en la mano.
—Ahora córrelo así.
Le dio un comando que tardó más de un minuto en terminar. Dejó un archivo de 78 MiB en target/. Iván lo ejecutó, mandó un pedido y el pedido se creó. Desde que lanzó el proceso hasta la primera respuesta pasaron 46 milisegundos.
—¿Cuarenta y seis? La de Spring tarda dos segundos. Hay que pasar todo a esto.
—¿Cuánto tardó en compilar?
—Un minuto y algo.
—¿Y cuántos pedidos por segundo atiende?
Iván no lo sabía. Nadie lo había medido.
—Mañana desayunamos en la fonda —dijo Lucía—. Llega temprano.
Martes, 7:30. La fonda de enfrente.
La cocina todavía no abría. La cocinera ya había picado la cebolla, hecho las salsas y puesto los frijoles. A la una iba a armar platos, nada más.
—La cocina se arma la noche anterior —dijo Lucía—. Por eso abre rápido. Pero abrir rápido no es cocinar rápido.
¿Qué cambia y qué no?
No cambia el restaurante: cambian las herramientas de cada papel.
La plantilla de esta entrega, estructura-quarkus, es la misma API de la entrega 5: recibe y consulta los pedidos de una tienda, le pregunta al proveedor de inventario cuántas piezas hay y a cuánto, y guarda en H2, una base en memoria. El paquete raíz es el mismo, mx.habil.pedidos, y los papeles también. Las reglas del cocinero, las medidas exactas (Dinero, Correo) y el que pasa en limpio pasaron casi sin cambios.
| Papel | En Spring Boot (entrega 5) | En Quarkus (esta entrega) |
|---|---|---|
El mesero, api | PedidoController, ResponseEntity | PedidoResource, RestResponse |
| La despensa | repository/ con Spring Data: una interfaz | model/repository/ con Panache: una clase |
El proveedor, client | RestClient; tiempo límite y reintento en la configuración | REST Client; @Timeout y @Retry en la misma interfaz |
El libro de quejas, exception | @RestControllerAdvice | Un ExceptionMapper y la extensión quarkus-http-problem |
| La salud | :8080/actuator/health | :9000/q/health, en otro puerto |
| La instalación del local | application.yml | application.yaml |
| Quién arranca todo | PedidosApplication, con su main | Nadie: Quarkus lo genera |
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 árbol¿Por qué la despensa se mudó a model/repository/? Por una decisión de la casa: el estándar de Hábil para Quarkus pone el repositorio de Panache junto a las fichas que guarda. Las flechas no cambian: solo el cocinero llega a la despensa.
¿Qué quiere decir «la noche anterior»?
Que el trabajo de preparar la cocina se hace al construir, no al abrir.
Cuando una aplicación de Java arranca, alguien tiene que leer la configuración, buscar las clases que son componentes, decidir quién recibe a quién y armar todo eso en memoria. En un marco tradicional se hace cada vez que la aplicación abre. Quarkus lo dice en una frase: su idea central es hacer «at build-time what traditional frameworks do at runtime: configuration parsing, classpath scanning, feature toggle based on classloading, and so on» [1].
En la fonda, la cocinera pica la cebolla antes de abrir. Quarkus revisa las clases cuando construyes, y a la hora de arrancar ya sabe quién es el mesero y a quién llama.
Esa revisión la hace ArC, su forma de conectar componentes. Sigue la especificación de Jakarta CDI («based on the Jakarta Contexts and Dependency Injection 4.1 specification»), pero no completa: «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 es el estándar de Java para eso que en la entrega 5 hacía el contenedor de Spring: tú declaras «el mesero necesita un jefe de cocina» y alguien le entrega uno.
En el código casi no se nota. El mesero recibe sus ayudantes por el constructor, igual que en la 5:
public PedidoResource(PedidoFacade facade, PedidoService service, PedidoMapper mapper) {Lo que cambia es cuándo se resuelve. Por eso Quarkus no necesita una clase con main: la genera al construir. La puerta es target/quarkus-app/quarkus-run.jar, dentro de una carpeta, y no un solo .jar.
Y hay algo más que se puede hacer con una cocina armada la noche anterior: compilarla toda, por adelantado, a un ejecutable del sistema operativo. Es el nativo: un programa que corre sin la máquina virtual de Java. Es lo que Lucía le dio a Iván.
¿Qué cambia en cada paquete?
El mesero, la despensa, el proveedor, el libro de quejas y la salud usan otras herramientas. Cada uno conserva su «nunca».
api, el mesero
@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 es «a new Jakarta REST (formerly known as JAX-RS) implementation» [4]: @Path, @POST y @GET son de ese estándar, no de Quarkus. En Jakarta REST, la clase que atiende una ruta se llama resource, recurso. @RunOnVirtualThread pide un hilo virtual para cada petición, como en la 5, porque el mesero espera al proveedor; la guía lo acota: «Virtual threads are useful for I/O-bound workloads only» [18].
Una diferencia medida: si pides /v1/pedidos/hola, que no es un identificador, la 5 contestaba 400 y ésta contesta 404. No es un descuido. La especificación de Jakarta REST lo manda: si un parámetro de la ruta no se puede convertir, «an implementation MUST generate an instance of NotFoundException (404 status)» [14]. Para Jakarta REST, esa ruta no existe.
Nunca va aquí: una regla del negocio. Igual que en la 5.
model/repository, la despensa
@ApplicationScoped
public class PedidoRepository implements PanacheRepositoryBase<PedidoEntity, UUID> {
}Panache es la capa de Quarkus para guardar con Hibernate. Ofrece dos estilos. En el primero, la ficha se guarda sola: la entidad hereda de PanacheEntity y trae sus propias consultas, como Person.findByName(…). Es el patrón de active record, registro activo. El segundo es el de esta plantilla: «the more classical repository pattern via PanacheRepository» [5]. La ficha es una entidad de JPA normal, y la despensa es otra clase. Se usa PanacheRepositoryBase porque el identificador es un UUID; para eso la guía indica «extend PanacheRepositoryBase instead of PanacheRepository and specify your ID type» [5].
¿Por qué la despensa aparte? Por la tercera regla de la entrega 5: lo que entra, lo que se guarda y lo que sale son cosas distintas. Si la ficha también guarda y consulta, trae consigo métodos como persist(): cualquiera que tenga una ficha en la mano podría intentar escribir en la base, aunque sea el mesero, y dentro de una transacción lo lograría [5]. Con la despensa aparte, solo el cocinero llega a ella, y la prueba de arquitectura lo vigila.
Nunca va aquí: una decisión. Y nunca: extends PanacheEntity en la ficha. Es el primer error de la lista, y el más callado.
client, el proveedor de afuera
@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);
}En la 5, el cliente era una clase que llamaba por HTTP. Aquí es una interfaz: tú declaras la ruta y Quarkus escribe la llamada [6]. La dirección del proveedor va en application.yaml, bajo la llave inventario.
Los dos cuidados de siempre están en la misma interfaz, con anotaciones de MicroProfile Fault Tolerance. La extensión ofrece varias, como @CircuitBreaker [7]; esta interfaz usa tres: @Timeout, @Retry y @ExponentialBackoff. Dos segundos de tiempo límite por intento y hasta dos reintentos: tres intentos en total. Se reintenta solo ante un tiempo vencido o una falla de red. Un «no existe» del proveedor es una respuesta y no se repite. Medido con el proveedor apagado: la API contesta 503, con "error_code":"PROVEEDOR_NO_DISPONIBLE", en medio segundo (0.534s), después de los tres intentos.
Nunca va aquí: una regla del pedido. Ni una llamada sin tiempo límite.
exception, el libro de quejas
@Provider
public class PedidosExceptionMapper extends ExceptionMapperBase<PedidosException>
implements ExceptionMapper<PedidosException> {
@Override
protected HttpProblem toProblem(PedidosException queja) {
return queja.codigo().aProblema(queja.getMessage());
}
}La forma de la respuesta es la de la 5: Problem Details, el RFC 9457 [16]. La da una extensión de la comunidad, quarkus-http-problem: «Unified error responses for Quarkus REST APIs via Problem Details for HTTP APIs (RFC9457 & RFC7807)» [15]. Un ExceptionMapper es la pieza de Jakarta REST que convierte una excepción en una respuesta [4]. Medido, pidiendo cuatro tazas cuando hay tres:
{"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"}El request_id es el mismo de la cabecera X-Request-ID y de la bitácora: con él se encuentra la visita. Nunca va aquí: un formato de error propio.
La salud, en otro puerto
Quarkus publica la salud en /q/health/live y /q/health/ready [8]. La plantilla la manda, con las métricas [20], a la interfaz de administración: con quarkus.management.enabled=true, esas rutas salen en el puerto 9000 y no en el de la API [9].
curl -s localhost:9000/q/health/readyContesta (sale en varias líneas; aquí va junta):
{"status":"UP","checks":[{"name":"Database connections health check","status":"UP","data":{"<default>":"UP"}}]}Medido: curl -s localhost:8080/q/health contesta 404. Lo de adentro no sale por la puerta de los clientes. Es como la cocina de la fonda: el inspector entra por la puerta de servicio, no por el comedor.
config, la instalación del local
application.yaml con la extensión quarkus-config-yaml [11]. Trae un aviso en su primera línea, porque nos pasó: una llave mal escrita no detiene a Quarkus. Lo vemos en el error 4.
¿Qué tan rápido abre?
Medido: el nativo crea su primer pedido en 46 milisegundos y pesa 60 MiB. Construirlo tardó 80 segundos y pidió 4 GiB.
Qué se midió. El tiempo desde que se lanza el proceso hasta la primera respuesta 201 a un POST /v1/pedidos. No basta con que el puerto abra: esa respuesta obliga a llamar dos veces al proveedor de inventario y a guardar en H2. Justo después de recibir ese 201 se lee con ps la memoria que ocupa el proceso (RSS, resident set size: la memoria física que tiene tomada). Cinco corridas seguidas de cada una y la mediana. El guion es herramientas/medir-arranque.py, y viene en la plantilla para que lo repitas.
Dónde. Una Mac con Apple Silicon (macOS arm64, 10 núcleos, 32 GB), el 18 de noviembre de 2026. Las dos de JVM con Java 25 (Temurin 25.0.5+8), sin opciones de memoria; Quarkus 3.40.1.2 y Spring Boot 4.1.2, la plantilla de la entrega 5.
| La misma API, en… | Primera respuesta (mediana de 5) | Memoria (RSS) | Las cinco corridas |
|---|---|---|---|
| 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, nativo | 46 ms | 60 MiB | 150, 67, 46, 38, 44 ms |
Repetimos la tanda en la misma Mac, con Temurin 25.0.4+7: Spring Boot, 2,617 ms y 427 MiB; Quarkus en la JVM, 1,378 ms y 266 MiB; el nativo, 47 ms y 60 MiB. Los milisegundos de la JVM se mueven de una tanda a otra; el orden no.
Lo que cuesta. Construir el nativo pidió GraalVM, el compilador que convierte la cocina armada en un ejecutable. En SDKMAN se instala como el candidato 25.5.5.0+3-graalce [21]. En la misma Mac tardó 80 segundos (72 de ellos compilando), llegó a 4.11 GiB de memoria y dejó un ejecutable de 78 MiB, que solo sirve para el sistema donde se construyó: el de una Mac no corre en Linux. La de JVM se construye en segundos. La guía oficial coincide: «native compilation takes minutes, JVM builds take seconds» [2].
Lo que esa tabla no te dice. La guía de Quarkus trae su propia comparación, con su aplicación y su máquina: en su banco de pruebas, el nativo llega a la primera petición en 581 ms contra 4,417 de la JVM y ocupa 95 MiB contra 304. Pero atiende 5,411 peticiones por segundo contra 13,265: «~59% below JVM» [2]. La razón la da la misma guía: en la JVM, el compilador optimiza mientras la aplicación corre, y en servicios de larga duración eso le gana al nativo [2]. Nosotros no medimos peticiones por segundo, y por eso no damos una cifra nuestra.
Es la pregunta de Lucía. El nativo abre rápido y ocupa poco. Cocinar rápido, durante horas, es otra cosa.
Entonces, ¿cuál? La plantilla corre en JVM: se construye en segundos, se revisa con las herramientas de siempre y arranca en poco más de un segundo, que para una API que vive días no pesa. El nativo vale cuando el arranque y la memoria sí pesan: funciones que nacen con cada petición, muchas réplicas pequeñas, escalar desde cero. En esta plantilla es el mismo código: decidir es cambiar el comando de construcción, no las capas. En otra aplicación quizá tengas que declarar lo que se carga por reflexión [2][3]. Y en Hábil se decide por escrito, con la medida que lo sostiene.
¿Siguen las flechas hacia adentro?
Sí, y la misma prueba lo vigila. Esta vez el guion siembra cuatro errores en lugar de uno.
Para Java, que el cocinero conozca al mesero sigue sin ser un error: compila. La regla la vigila CapasTest, escrita con ArchUnit, que revisa las clases compiladas [17]. Las capas son las mismas de la 5:
.whereLayer("api").mayNotBeAccessedByAnyLayer()
.whereLayer("facade").mayOnlyBeAccessedByLayers("api")
.whereLayer("service").mayOnlyBeAccessedByLayers("api", "facade")
.whereLayer("repository").mayOnlyBeAccessedByLayers("service")
.whereLayer("client").mayOnlyBeAccessedByLayers("facade", "service")Y una regla aparte: ninguna clase de api puede depender de una entity. El mesero entrega el ticket, nunca la ficha.
herramientas/probar-frontera.sh trabaja en una copia temporal. Primero corre el control: el proyecto tal como está tiene que pasar. Después siembra cuatro errores, uno a la vez. Cada uno tiene que compilar, y CapasTest tiene que fallar en una sola regla, por la razón exacta. Ésta es la salida real, recortada:
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)¿Y si el guion miente? Lo saboteamos. Con la regla de la ficha apuntando a otro paquete, se detiene en rojo en la primera fuga. Sin la regla de capas de api, se detiene en la violación. Un guion que no sabe fallar no demuestra nada.
Las pruebas son 82, contadas en los informes de target/surefire-reports/, no en el BUILD SUCCESS. Las que levantan la aplicación usan @QuarkusTest. Las que comparten perfil reutilizan la misma instancia de Quarkus; una prueba con otro perfil, como la del proveedor apagado, la reinicia [23].
¿Cuáles son cinco errores frecuentes?
Tres son de un papel haciendo el trabajo de otro, como en la 5. Dos son nuevos: confundir abrir con cocinar, y confiar en lo que no avisa.
1. La ficha que también es la despensa
La entidad hereda de PanacheEntity y se guarda sola.
Es la forma que la guía de Panache enseña primero [5], y funciona. Lo medimos en un clon de la plantilla: hicimos que PedidoEntity heredara de PanacheEntityBase y corrimos todo. 82 de 82 en verde. Ninguna prueba de la plantilla lo ve, porque las flechas siguen bien: la ficha no importa a nadie. Lo que cambió es que ahora la ficha trae persist(), y cualquiera con una ficha en la mano, dentro de una transacción, podría escribir en la base.
Lo que lo delata es una búsqueda:
grep -rn 'extends PanacheEntity' src/mainCero resultados es lo que quieres. Es la tarea del lunes.
2. Pasar todo a nativo porque abre rápido
Medir el arranque y concluir sobre el rendimiento.
Es el de Iván. El nativo abre en milisegundos, pero en el banco de pruebas de la guía oficial atiende ~59 % menos peticiones por segundo, y su construcción tarda minutos y pide gigas de memoria [2]. Lo delata una pregunta: ¿qué es lo que de verdad te cuesta, abrir o atender?
3. El binario que arranca y muere en su primer pedido
Probar el nativo con la salud y no con un pedido de verdad.
Al compilar a nativo, solo entra lo que el compilador ve usado. Lo que una biblioteca carga por su nombre, en el momento, puede quedarse fuera. La guía de Quarkus describe el peor caso: no hay excepción, pero «the JSON result would be completely empty» [3]. La salud puede contestar UP mientras el primer pedido sale vacío. Por eso la plantilla no da por bueno el nativo con que arranque: le pide un pedido que llama al proveedor y guarda en la base. Lo medimos así: el nativo contestó 201, 404, 409, 422 y 400 con su Problem Details, y 503 con el proveedor apagado.
4. Una llave que se ignora en silencio
Una configuración mal escrita no falla: no hace nada.
Nos pasó con la plantilla. Para acortar el tiempo límite en las pruebas, escribimos la llave con el nombre de la interfaz, InventarioApi/producto. Quarkus no se quejó, y el tiempo límite siguió en 2 segundos. La llave correcta lleva el nombre de la clase que Quarkus genera para la interfaz, InventarioApi$$CDIWrapper/producto. Quarkus sí avisa de una llave que no reconoce, con «Unrecognized configuration key», pero solo de las que empiezan con quarkus.; medido con una falsa de cada tipo. Lo que lo delata es una prueba que dependa de esa llave: la de tiempo límite se pone roja si la llave no se aplica.
5. Copiar las anotaciones de Spring
Buscar @RestController, @Service y @Autowired en un proyecto de Quarkus.
En Quarkus, el mesero es un resource de Jakarta REST, y los componentes se conectan con CDI [4][10]. Quarkus tiene extensiones que entienden algunas anotaciones de Spring [19], pero la plantilla no las usa: si el proyecto es de Quarkus, se escribe como Quarkus, y quien lo lea después encuentra lo que la documentación oficial enseña. Si un equipo decide usarlas, que sea por escrito, no porque alguien copió un ejemplo.
| Error | Lo que lo delata | Fuente |
|---|---|---|
| 1. La ficha que también es la despensa | grep -rn 'extends PanacheEntity' src/main | [5] · medición |
| 2. Todo a nativo porque abre rápido | Peticiones por segundo, no solo el arranque | [2] |
| 3. El nativo que muere en su primer pedido | Un pedido de verdad, no la salud | [3] · medición |
| 4. Una llave que no hace nada | Una prueba que dependa de esa llave | medición |
| 5. Anotaciones de Spring en Quarkus | @RestController o @Autowired en src/main | [4][10][19] |
Ejercicio: ¿puedes esconder la ficha en el ticket?
Vas a hacer que el mesero entregue la ficha del archivo dentro de una respuesta, ver que Java la acepta y ver cómo la prueba y el guion te avisan.
Necesitas Java 25 (java -version), Git 2.23 o más nuevo (por git restore), bash y curl; unos 25 minutos. Maven no: lo trae el proyecto. Si todavía no tienes Java 25, la entrega 5 y el README de la plantilla explican cómo instalarlo con SDKMAN; en Windows, usa WSL. El nativo no hace falta para el ejercicio.
Paso 1. Clona y comprueba que todo está en verde.
git clone https://github.com/HabilMX/estructura-quarkus
cd estructura-quarkus
./mvnw verify
bash herramientas/probar-frontera.shLa primera vez tarda: baja Maven y las bibliotecas. Debes ver Tests run: 82, 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 mesero, PedidoResource, una ruta que devuelve la PedidoEntity dentro de una RestResponse. Anota: ¿compila? ¿Qué dice CapasTest? ¿Y el guion de la frontera?
Paso 3. Esconde la ficha. La primera línea quita la última llave de la clase y deja una copia .bak; la segunda agrega la ruta y cierra la clase. La sintaxis sirve en macOS y en Linux; el ejercicio completo se probó en 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 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.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 no se fijó en el tipo que devuelve el método, sino en de quién depende: la ficha iba escondida dentro de la respuesta, y aun así la encontró.
Paso 4. Pregúntale al guion.
bash herramientas/probar-frontera.shSe pone rojo, sin pasar del control:
❌ 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. Antes, mira qué cambió:
git diff --stat -- src/main/java/mx/habil/pedidos/api/PedidoResource.javaDebes ver 1 file changed, 5 insertions(+): la ruta nueva. 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 [22]:
git restore src/main/java/mx/habil/pedidos/api/PedidoResource.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/api/PedidoResource.java.bakConsérvala hasta que estés seguro de que no la necesitas. Luego bórrala con rm -i, que pregunta antes.
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 PedidoResource.java termine en una sola llave }.
Para ir más lejos (opcional): convierte la ficha en despensa. En PedidoEntity, haz que la clase herede de PanacheEntityBase (agrega import io.quarkus.hibernate.orm.panache.PanacheEntityBase; y cambia public class PedidoEntity { por public class PedidoEntity extends PanacheEntityBase {). Antes, predice: ¿cuántas pruebas fallan? Respuesta medida: ninguna, 82 de 82. Corre grep -rn 'extends PanacheEntity' src/main: ése sí lo encuentra. Regresa igual que en el paso 5.
Para llevar
Tres preguntas para hacerle a tu repositorio esta semana.
- ¿Cuántas fichas de tu proyecto heredan de
PanacheEntity? Cada una es una entidad que trae sus propios métodos para guardarse. - Si usas el nativo, ¿qué medida lo justificó: el arranque, la memoria o las peticiones por segundo? ¿Quedó escrita?
- ¿Qué prueba se pone roja si una llave de tu configuración deja de aplicarse? Si la respuesta es «ninguna», esa llave puede estar sin hacer nada desde hace meses.
¿Qué sigue?
El restaurante también tiene comedor.
Un viernes, a Iván le pidieron mover un botón en la pantalla donde la tienda ve sus pedidos. El proyecto era de React. Abrió la carpeta src/ y encontró ochenta archivos sueltos, todos al mismo nivel: botones, pantallas, llamadas a la API, todo junto.
Había aprendido a preguntar de quién es cada trabajo. Esta vez no encontraba ni los papeles. El domingo 13 de diciembre, en la entrega 7, la última de la serie: cómo se acomoda un frontend con React, qué va en cada carpeta, y la plantilla que lo comprueba.
La plantilla y el curso
- Plantilla: github.com/HabilMX/estructura-quarkus. Se usa como plantilla de GitHub o se clona. El README explica cada paquete con su «nunca», el camino de un pedido, lo que cambió respecto de Spring Boot, cómo medir el arranque y la memoria, 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, que ya trae el JDK. La base es H2, en memoria: lo más simple que corre a la primera; los datos se borran al apagar. La salud y las métricas, en el puerto 9000. - Versiones: Java 25 con Temurin 25.0.5+8. Quarkus 3.40.1.2: la 3.40 es su versión de soporte largo más reciente [13], y una versión de soporte largo se mantiene 12 meses, con una nueva cada seis [12]. Maven por el Wrapper. GraalVM CE
25.5.5.0+3-graalce, solo para el nativo. Se probó en macOS arm64. Linux todavía no: el CI está escrito para Ubuntu y macOS, y corre cuando el repositorio público exista. - Curso de Java de Hábil: si los
record, Maven o las pruebas con JUnit son nuevos para ti, empieza ahí: Curso de Java. Y si no leíste la entrega 5, léela primero: ésta da por sabidos los papeles del restaurante.
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, la misma base 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 18 de noviembre de 2026. Las citas en inglés se reproducen tal cual.
Referencias
- Quarkus, «Container First»: «Build Time Processing». https://quarkus.io/container-first/
- Quarkus, «Building a Native Executable»: «Comparing JVM, Leyden AOT, and native modes» (banco de pruebas del 21-abr-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» y «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» (referencia de 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 de julio de 2023. https://quarkus.io/blog/lts-releases/
- G. Smet, «Quarkus 3.40 LTS - new LTS version», blog de Quarkus, 30 de septiembre de 2026. https://quarkus.io/blog/quarkus-3-40-released/
- Eclipse Foundation, «Jakarta RESTful Web Services 3.1», conversión de parámetros. 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 y S. Dalal, «RFC 9457: Problem Details for HTTP APIs», IETF, julio de 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, candidatos de Java para 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
¿Su operación tiene estos desafíos?
¿Prefiere correo? Escríbanos a hola@habil.mx