A estrutura de um projeto (6): a cozinha que se monta na véspera
Por Dorian Chávez · cofundador e Chief Executive Officer da Hábil ·
A mesma API de pedidos, do Spring Boot ao Quarkus: o que muda em cada pacote, a inicialização e a memória medidas, e o que esse número não conta.
A estrutura de um projeto · entrega 6 de 7 · Quarkus
Cenário: os personagens e a história são inventados. Os dados técnicos e as citações levam a fonte no final.
Em 1 minuto
- É o mesmo restaurante da entrega 5:
apié o garçom,serviceo cozinheiro,repositorya despensa. O que muda é a cozinha: a ferramenta de cada papel. - A ideia central do Quarkus é fazer «at build-time what traditional frameworks do at runtime» [1]. A cozinha se monta na véspera, e por isso abre rápido.
- Medido no template, até o primeiro pedido criado: Spring Boot, 2,2 s e 437 MiB; Quarkus na JVM (a máquina virtual que executa o Java), 1,2 s e 270 MiB; Quarkus compilado para nativo (um executável que não precisa da JVM), 46 ms e 60 MiB.
- Abrir rápido não é cozinhar rápido. No banco de testes do guia oficial, o nativo atende ~59% menos requisições por segundo que a JVM [2]. O nativo se escolhe pela inicialização e pela memória, com a medida na mão.
- As setas continuam apontando para dentro, e o mesmo teste de arquitetura fica vermelho se alguém as inverte. Há um erro que nenhum teste do template vê: ele aparece com um
grep. - Para segunda-feira: procure
extends PanacheEntityno projeto. Cada resultado é uma ficha do arquivo que também faz as vezes de despensa.
Neste artigo
- O que aconteceu na segunda às 9:12?
- O que muda e o que não muda?
- O que quer dizer «na véspera»?
- O que muda em cada pacote?
- Quão rápido ela abre?
- As setas continuam para dentro?
- Quais são cinco erros frequentes?
- Exercício: dá para esconder a ficha no tíquete?
- Para levar
- O que vem depois?
- O template e o curso
- O que a Hábil faz?
- Referências
O que aconteceu na segunda às 9:12?
O Iván viu uma API iniciar em 46 milissegundos e quis passar tudo para nativo. A Lucía lhe fez duas perguntas.
Segunda-feira, 9:05. Terceiro andar.
A API de pedidos nova tinha as pastas de sempre: api, facade, service. O Iván procurou o garçom e encontrou PedidoResource. Não havia @RestController, não havia classe com main, e a despensa não estava onde ele esperava: morava dentro de model/.
Ele a construiu e a iniciou. O log disse:
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.Duas portas. Anotou a dúvida e seguiu.
Segunda-feira, 9:12.
A Lucía passou pela mesa dele com o café na mão.
— Agora roda assim.
Ela lhe deu um comando que levou mais de um minuto para terminar. Deixou um arquivo de 78 MiB em target/. O Iván o executou, mandou um pedido e o pedido foi criado. Do momento em que lançou o processo até a primeira resposta passaram 46 milissegundos.
— Quarenta e seis? A do Spring leva dois segundos. Tem que passar tudo para isso.
— Quanto tempo levou para compilar?
— Um minuto e pouco.
— E quantos pedidos por segundo ela atende?
O Iván não sabia. Ninguém tinha medido.
— Amanhã tomamos café da manhã no restaurante simples em frente — disse a Lucía. — Chega cedo.
Terça-feira, 7:30. O restaurante simples em frente.
A cozinha ainda não tinha aberto. A cozinheira já tinha picado a cebola, feito os molhos e posto o feijão no fogo. À uma da tarde ia só montar pratos.
— A cozinha se monta na véspera — disse a Lucía. — Por isso abre rápido. Mas abrir rápido não é cozinhar rápido.
O que muda e o que não muda?
Não muda o restaurante: mudam as ferramentas de cada papel.
O template desta entrega, estructura-quarkus, é a mesma API da entrega 5: recebe e consulta os pedidos de uma loja, pergunta ao fornecedor de estoque quantas peças há e a que preço, e guarda no H2, um banco em memória. O pacote raiz é o mesmo, mx.habil.pedidos, e os papéis também. As regras do cozinheiro, as medidas exatas (Dinero, Correo) e quem passa a limpo vieram quase sem mudanças.
| Papel | No Spring Boot (entrega 5) | No Quarkus (esta entrega) |
|---|---|---|
O garçom, api | PedidoController, ResponseEntity | PedidoResource, RestResponse |
| A despensa | repository/ com Spring Data: uma interface | model/repository/ com Panache: uma classe |
O fornecedor, client | RestClient; tempo limite e nova tentativa na configuração | REST Client; @Timeout e @Retry na própria interface |
O livro de reclamações, exception | @RestControllerAdvice | Um ExceptionMapper e a extensão quarkus-http-problem |
| A saúde | :8080/actuator/health | :9000/q/health, em outra porta |
| A instalação do local | application.yml | application.yaml |
| Quem inicia tudo | PedidosApplication, com o main | Ninguém: o Quarkus o gera |
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 árbolPor que a despensa se mudou para model/repository/? Por uma decisão da casa: o padrão da Hábil para Quarkus põe o repositório do Panache junto às fichas que ele guarda. As setas não mudam: só o cozinheiro chega à despensa.
O que quer dizer «na véspera»?
Que o trabalho de preparar a cozinha se faz ao construir, não ao abrir.
Quando uma aplicação Java inicia, alguém tem que ler a configuração, procurar as classes que são componentes, decidir quem recebe quem e montar tudo isso na memória. Num framework tradicional, isso se faz cada vez que a aplicação abre. O Quarkus diz isso numa frase: a ideia central dele é fazer «at build-time what traditional frameworks do at runtime: configuration parsing, classpath scanning, feature toggle based on classloading, and so on» [1].
No restaurante simples, a cozinheira pica a cebola antes de abrir. O Quarkus revisa as classes na construção, e na hora de iniciar já sabe quem é o garçom e quem ele chama.
Essa revisão é feita pelo ArC, a forma do Quarkus de conectar componentes. Ele segue a especificação Jakarta CDI («based on the Jakarta Contexts and Dependency Injection 4.1 specification»), mas não inteira: «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 é o padrão do Java para aquilo que, na entrega 5, o contêiner do Spring fazia: declara-se «o garçom precisa de um chefe de cozinha» e alguém lhe entrega um.
No código quase não se nota. O garçom recebe os ajudantes pelo construtor, igual à entrega 5:
public PedidoResource(PedidoFacade facade, PedidoService service, PedidoMapper mapper) {O que muda é quando isso se resolve. Por isso o Quarkus não precisa de uma classe com main: ele a gera na construção. A porta de entrada é target/quarkus-app/quarkus-run.jar, dentro de uma pasta, e não um único .jar.
E há algo mais que se pode fazer com uma cozinha montada na véspera: compilá-la toda, de antemão, para um executável do sistema operacional. É o nativo: um programa que roda sem a máquina virtual do Java. É o que a Lucía deu ao Iván.
O que muda em cada pacote?
O garçom, a despensa, o fornecedor, o livro de reclamações e a saúde usam outras ferramentas. Cada um conserva o próprio «nunca».
api, o garçom
@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();
}O Quarkus REST é «a new Jakarta REST (formerly known as JAX-RS) implementation» [4]: @Path, @POST e @GET são desse padrão, não do Quarkus. No Jakarta REST, a classe que atende uma rota se chama resource, recurso. @RunOnVirtualThread pede uma thread virtual para cada requisição, como na entrega 5, porque o garçom espera o fornecedor; o guia faz a ressalva: «Virtual threads are useful for I/O-bound workloads only» [18].
Uma diferença medida: ao pedir /v1/pedidos/hola, que não é um identificador, a entrega 5 respondia 400 e esta responde 404. Não é descuido. A especificação do Jakarta REST manda assim: se um parâmetro da rota não pode ser convertido, «an implementation MUST generate an instance of NotFoundException (404 status)» [14]. Para o Jakarta REST, essa rota não existe.
Nunca vai aqui: uma regra de negócio. Igual à entrega 5.
model/repository, a despensa
@ApplicationScoped
public class PedidoRepository implements PanacheRepositoryBase<PedidoEntity, UUID> {
}O Panache é a camada do Quarkus para guardar com Hibernate. Oferece dois estilos. No primeiro, a ficha se guarda sozinha: a entidade herda de PanacheEntity e traz as próprias consultas, como Person.findByName(…). É o padrão active record, registro ativo. O segundo é o deste template: «the more classical repository pattern via PanacheRepository» [5]. A ficha é uma entidade JPA normal, e a despensa é outra classe. Usa-se PanacheRepositoryBase porque o identificador é um UUID; para isso o guia indica «extend PanacheRepositoryBase instead of PanacheRepository and specify your ID type» [5].
Por que a despensa à parte? Pela terceira regra da entrega 5: o que entra, o que se guarda e o que sai são coisas diferentes. Se a ficha também guarda e consulta, traz consigo métodos como persist(): qualquer um com uma ficha na mão poderia tentar escrever no banco, até o garçom, e dentro de uma transação conseguiria [5]. Com a despensa à parte, só o cozinheiro chega a ela, e o teste de arquitetura vigia isso.
Nunca vai aqui: uma decisão. E nunca: extends PanacheEntity na ficha. É o primeiro erro da lista, e o mais silencioso.
client, o fornecedor de fora
@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);
}Na entrega 5, o cliente era uma classe que chamava por HTTP. Aqui é uma interface: declara-se a rota e o Quarkus escreve a chamada [6]. O endereço do fornecedor vai em application.yaml, sob a chave inventario.
Os dois cuidados de sempre estão na própria interface, com anotações do MicroProfile Fault Tolerance. A extensão oferece várias, como @CircuitBreaker [7]; esta interface usa três: @Timeout, @Retry e @ExponentialBackoff. Dois segundos de tempo limite por tentativa e até duas novas tentativas: três tentativas no total. Só se tenta de novo diante de um tempo esgotado ou de uma falha de rede. Um «não existe» do fornecedor é uma resposta e não se repete. Medido com o fornecedor desligado: a API responde 503, com "error_code":"PROVEEDOR_NO_DISPONIBLE", em meio segundo (0.534s), depois das três tentativas.
Nunca vai aqui: uma regra do pedido. Nem uma chamada sem tempo limite.
exception, o livro de reclamações
@Provider
public class PedidosExceptionMapper extends ExceptionMapperBase<PedidosException>
implements ExceptionMapper<PedidosException> {
@Override
protected HttpProblem toProblem(PedidosException queja) {
return queja.codigo().aProblema(queja.getMessage());
}
}A forma da resposta é a da entrega 5: Problem Details, o RFC 9457 [16]. Quem a dá é uma extensão da comunidade, quarkus-http-problem: «Unified error responses for Quarkus REST APIs via Problem Details for HTTP APIs (RFC9457 & RFC7807)» [15]. Um ExceptionMapper é a peça do Jakarta REST que converte uma exceção numa resposta [4]. Medido, pedindo quatro canecas quando há três:
{"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"}O request_id é o mesmo do cabeçalho X-Request-ID e do log: com ele se encontra a visita. Nunca vai aqui: um formato de erro próprio.
A saúde, em outra porta
O Quarkus publica a saúde em /q/health/live e /q/health/ready [8]. O template a manda, com as métricas [20], para a interface de administração: com quarkus.management.enabled=true, essas rotas saem na porta 9000 e não na da API [9].
curl -s localhost:9000/q/health/readyResponde (sai em várias linhas; aqui vai junta):
{"status":"UP","checks":[{"name":"Database connections health check","status":"UP","data":{"<default>":"UP"}}]}Medido: curl -s localhost:8080/q/health responde 404. O que é de dentro não sai pela porta dos clientes. É como a cozinha do restaurante simples: o fiscal entra pela porta de serviço, não pelo salão.
config, a instalação do local
application.yaml com a extensão quarkus-config-yaml [11]. Traz um aviso na primeira linha, porque isso aconteceu conosco: uma chave mal escrita não detém o Quarkus. Isso aparece no erro 4.
Quão rápido ela abre?
Medido: o nativo cria o primeiro pedido em 46 milissegundos e pesa 60 MiB. Construí-lo levou 80 segundos e pediu 4 GiB.
O que se mediu. O tempo desde que se lança o processo até a primeira resposta 201 a um POST /v1/pedidos. Não basta que a porta abra: essa resposta obriga a chamar duas vezes o fornecedor de estoque e a guardar no H2. Logo depois de receber esse 201, lê-se com ps a memória que o processo ocupa (RSS, resident set size: a memória física que ele tem tomada). Cinco execuções seguidas de cada uma, e a mediana. O script é herramientas/medir-arranque.py, e vem no template para repetir a medição.
Onde. Um Mac com Apple Silicon (macOS arm64, 10 núcleos, 32 GB), em 18 de novembro de 2026. As duas de JVM com Java 25 (Temurin 25.0.5+8), sem opções de memória; Quarkus 3.40.1.2 e Spring Boot 4.1.2, o template da entrega 5.
| A mesma API, em… | Primeira resposta (mediana de 5) | Memória (RSS) | As cinco execuções |
|---|---|---|---|
| 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 a rodada no mesmo Mac, com Temurin 25.0.4+7: Spring Boot, 2.617 ms e 427 MiB; Quarkus na JVM, 1.378 ms e 266 MiB; o nativo, 47 ms e 60 MiB. Os milissegundos da JVM se mexem de uma rodada para outra; a ordem, não.
O que custa. Construir o nativo pediu o GraalVM, o compilador que converte a cozinha montada num executável. No SDKMAN ele se instala como o candidato 25.5.5.0+3-graalce [21]. No mesmo Mac levou 80 segundos (72 deles compilando), chegou a 4,11 GiB de memória e deixou um executável de 78 MiB, que só serve para o sistema onde foi construído: o de um Mac não roda no Linux. A de JVM se constrói em segundos. O guia oficial concorda: «native compilation takes minutes, JVM builds take seconds» [2].
O que essa tabela não conta. O guia do Quarkus traz a própria comparação, com a aplicação e a máquina dele: no banco de testes do guia, o nativo chega à primeira requisição em 581 ms contra 4.417 da JVM e ocupa 95 MiB contra 304. Mas atende 5.411 requisições por segundo contra 13.265: «~59% below JVM» [2]. A razão quem dá é o mesmo guia: na JVM, o compilador otimiza enquanto a aplicação roda, e em serviços de longa duração isso ganha do nativo [2]. Nós não medimos requisições por segundo, e por isso não damos um número nosso.
É a pergunta da Lucía. O nativo abre rápido e ocupa pouco. Cozinhar rápido, durante horas, é outra coisa.
Então, qual? O template roda em JVM: constrói-se em segundos, revisa-se com as ferramentas de sempre e inicia em pouco mais de um segundo, o que, para uma API que vive dias, não pesa. O nativo vale quando a inicialização e a memória pesam de fato: funções que nascem a cada requisição, muitas réplicas pequenas, escalar do zero. Neste template é o mesmo código: decidir é mudar o comando de construção, não as camadas. Em outra aplicação talvez seja preciso declarar o que se carrega por reflexão [2][3]. E na Hábil isso se decide por escrito, com a medida que o sustenta.
As setas continuam para dentro?
Sim, e o mesmo teste vigia isso. Desta vez o script planta quatro erros em vez de um.
Para o Java, o cozinheiro conhecer o garçom continua não sendo um erro: compila. Quem vigia a regra é o CapasTest, escrito com ArchUnit, que revisa as classes compiladas [17]. As camadas são as mesmas da entrega 5:
.whereLayer("api").mayNotBeAccessedByAnyLayer()
.whereLayer("facade").mayOnlyBeAccessedByLayers("api")
.whereLayer("service").mayOnlyBeAccessedByLayers("api", "facade")
.whereLayer("repository").mayOnlyBeAccessedByLayers("service")
.whereLayer("client").mayOnlyBeAccessedByLayers("facade", "service")E uma regra à parte: nenhuma classe de api pode depender de uma entity. O garçom entrega o tíquete, nunca a ficha.
herramientas/probar-frontera.sh trabalha numa cópia temporária. Primeiro roda o controle: o projeto tal como está tem que passar. Depois planta quatro erros, um de cada vez. Cada um tem que compilar, e o CapasTest tem que falhar numa única regra, pela razão exata. Esta é a saída 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)E se o script mentir? Nós o sabotamos. Com a regra da ficha apontando para outro pacote, ele para no vermelho no primeiro vazamento. Sem a regra de camadas de api, para na violação. Um script que não sabe falhar não demonstra nada.
Os testes são 82, contados nos relatórios de target/surefire-reports/, não no BUILD SUCCESS. Os que sobem a aplicação usam @QuarkusTest. Os que compartilham perfil reutilizam a mesma instância do Quarkus; um teste com outro perfil, como o do fornecedor desligado, a reinicia [23].
Quais são cinco erros frequentes?
Três são de um papel fazendo o trabalho de outro, como na entrega 5. Dois são novos: confundir abrir com cozinhar, e confiar no que não avisa.
1. A ficha que também é a despensa
A entidade herda de PanacheEntity e se guarda sozinha.
É a forma que o guia do Panache ensina primeiro [5], e funciona. Medimos num clone do template: fizemos PedidoEntity herdar de PanacheEntityBase e rodamos tudo. 82 de 82 no verde. Nenhum teste do template percebe, porque as setas continuam certas: a ficha não importa ninguém. O que mudou é que agora a ficha traz persist(), e qualquer um com uma ficha na mão, dentro de uma transação, poderia escrever no banco.
O que denuncia é uma busca:
grep -rn 'extends PanacheEntity' src/mainZero resultados é o que se quer. É a tarefa de segunda-feira.
2. Passar tudo para nativo porque abre rápido
Medir a inicialização e tirar conclusões sobre o desempenho.
É o do Iván. O nativo abre em milissegundos, mas no banco de testes do guia oficial atende ~59% menos requisições por segundo, e a construção leva minutos e pede gigas de memória [2]. Quem denuncia é uma pergunta: o que de fato custa, abrir ou atender?
3. O binário que inicia e morre no primeiro pedido
Testar o nativo com a saúde e não com um pedido de verdade.
Ao compilar para nativo, só entra o que o compilador vê sendo usado. O que uma biblioteca carrega pelo nome, na hora, pode ficar de fora. O guia do Quarkus descreve o pior caso: não há exceção, mas «the JSON result would be completely empty» [3]. A saúde pode responder UP enquanto o primeiro pedido sai vazio. Por isso o template não dá o nativo por bom só porque inicia: pede a ele um pedido que chama o fornecedor e guarda no banco. Medimos assim: o nativo respondeu 201, 404, 409, 422 e 400 com o Problem Details correspondente, e 503 com o fornecedor desligado.
4. Uma chave ignorada em silêncio
Uma configuração mal escrita não falha: não faz nada.
Aconteceu conosco no template. Para encurtar o tempo limite nos testes, escrevemos a chave com o nome da interface, InventarioApi/producto. O Quarkus não reclamou, e o tempo limite continuou em 2 segundos. A chave correta leva o nome da classe que o Quarkus gera para a interface, InventarioApi$$CDIWrapper/producto. O Quarkus avisa, sim, de uma chave que não reconhece, com «Unrecognized configuration key», mas só das que começam com quarkus.; medido com uma falsa de cada tipo. O que denuncia é um teste que dependa dessa chave: o de tempo limite fica vermelho se a chave não se aplica.
5. Copiar as anotações do Spring
Procurar @RestController, @Service e @Autowired num projeto Quarkus.
No Quarkus, o garçom é um resource do Jakarta REST, e os componentes se conectam com CDI [4][10]. O Quarkus tem extensões que entendem algumas anotações do Spring [19], mas o template não as usa: se o projeto é Quarkus, escreve-se como Quarkus, e quem o ler depois encontra o que a documentação oficial ensina. Se uma equipe decidir usá-las, que seja por escrito, não porque alguém copiou um exemplo.
| Erro | O que denuncia | Fonte |
|---|---|---|
| 1. A ficha que também é a despensa | grep -rn 'extends PanacheEntity' src/main | [5] · medição |
| 2. Tudo para nativo porque abre rápido | Requisições por segundo, não só a inicialização | [2] |
| 3. O nativo que morre no primeiro pedido | Um pedido de verdade, não a saúde | [3] · medição |
| 4. Uma chave que não faz nada | Um teste que dependa dessa chave | medição |
| 5. Anotações do Spring no Quarkus | @RestController ou @Autowired em src/main | [4][10][19] |
Exercício: dá para esconder a ficha no tíquete?
O exercício faz o garçom entregar a ficha do arquivo dentro de uma resposta, mostra que o Java a aceita e mostra como o teste e o script avisam.
É preciso ter Java 25 (java -version), Git 2.23 ou mais novo (por causa do git restore), bash e curl; uns 25 minutos. Maven não: o projeto o traz. Se ainda não houver Java 25 na máquina, a entrega 5 e o README do template explicam como instalá-lo com SDKMAN; no Windows, use o WSL. O nativo não faz falta para o exercício.
Passo 1. Clone e confira que tudo está no verde.
git clone https://github.com/HabilMX/estructura-quarkus
cd estructura-quarkus
./mvnw verify
bash herramientas/probar-frontera.shNa primeira vez demora: baixa o Maven e as bibliotecas. Deve aparecer Tests run: 82, Failures: 0, Errors: 0, Skipped: 0, depois BUILD SUCCESS e, no fim do script, ✅ frontera: se sostiene.
Use este clone só para praticar. Assim, toda mudança que aparecer nele é do exercício.
Passo 2. Preveja antes de mexer. O exercício acrescenta ao garçom, PedidoResource, uma rota que devolve a PedidoEntity dentro de uma RestResponse. Anote: compila? O que diz o CapasTest? E o script da fronteira?
Passo 3. Esconda a ficha. A primeira linha tira a última chave da classe e deixa uma cópia .bak; a segunda acrescenta a rota e fecha a classe. A sintaxe serve no macOS e no Linux; o exercício completo foi testado no 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 sem dizer nada: compilou. O teste, não. Entre muitas linhas, as que importam:
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)O ArchUnit não olhou o tipo que o método devolve, e sim de quem ele depende: a ficha ia escondida dentro da resposta, e mesmo assim ele a encontrou.
Passo 4. Pergunte ao script.
bash herramientas/probar-frontera.shFica vermelho, sem passar do controle:
❌ el control NO pasó: tu proyecto, tal como está, ya rompe una regla de CapasTest:Esse é o controle trabalhando: não dá para demonstrar que o teste sabe falhar se o projeto já o tem falhando.
Passo 5. Desfaça só o que foi mexido. Antes, veja o que mudou:
git diff --stat -- src/main/java/mx/habil/pedidos/api/PedidoResource.javaDeve aparecer 1 file changed, 5 insertions(+): a rota nova. Se aparecer algo mais, não é do exercício: guarde antes de seguir. Se só estiver o do exercício, restaure esse arquivo. O git restore só mexe nos caminhos indicados [22]:
git restore src/main/java/mx/habil/pedidos/api/PedidoResource.java
bash herramientas/probar-frontera.sh
git status --shortA fronteira volta ao verde, e o git status mostra o que sobra, a cópia que o sed fez:
?? src/main/java/mx/habil/pedidos/api/PedidoResource.java.bakGuarde-a até ter certeza de que não faz falta. Depois apague-a com rm -i, que pergunta antes.
Como saber que deu certo: foram seis execuções e três desfechos. Verde, quatro vezes: as duas do passo 1, test-compile no passo 3 e a fronteira do passo 5. Vermelho do teste, uma vez: Failures: 1 no passo 3. E o vermelho do script, «el control NO pasó», no passo 4. Se no passo 3 o test-compile marcar um erro, confira que PedidoResource.java termina numa única chave }.
Para ir mais longe (opcional): transforme a ficha em despensa. Em PedidoEntity, faça a classe herdar de PanacheEntityBase (acrescente import io.quarkus.hibernate.orm.panache.PanacheEntityBase; e troque public class PedidoEntity { por public class PedidoEntity extends PanacheEntityBase {). Antes, preveja: quantos testes falham? Resposta medida: nenhum, 82 de 82. Rode grep -rn 'extends PanacheEntity' src/main: esse sim encontra. Desfaça igual ao passo 5.
Para levar
Três perguntas para fazer ao repositório esta semana.
- Quantas fichas do projeto herdam de
PanacheEntity? Cada uma é uma entidade que traz os próprios métodos para se guardar. - Se o projeto usa o nativo, que medida o justificou: a inicialização, a memória ou as requisições por segundo? Ficou escrita?
- Que teste fica vermelho se uma chave da configuração deixar de ser aplicada? Se a resposta for «nenhum», essa chave pode estar sem fazer nada há meses.
O que vem depois?
O restaurante também tem salão.
Numa sexta-feira, pediram ao Iván que mudasse um botão de lugar na tela onde a loja vê os pedidos. O projeto era em React. Ele abriu a pasta src/ e encontrou oitenta arquivos soltos, todos no mesmo nível: botões, telas, chamadas à API, tudo junto.
Tinha aprendido a perguntar de quem é cada trabalho. Desta vez não encontrava nem os papéis. No domingo, 13 de dezembro, na entrega 7, a última da série: como se organiza um frontend com React, o que vai em cada pasta, e o template que o comprova.
O template e o curso
- Template: github.com/HabilMX/estructura-quarkus. Usa-se como template do GitHub ou se clona. O README explica cada pacote com o «nunca» correspondente, o caminho de um pedido, o que mudou em relação ao Spring Boot, como medir a inicialização e a memória, o que não traz (autenticação, um banco de verdade, contrato OpenAPI), quando acrescentar cada coisa e como tirar o exemplo. O código é MIT; o texto e as explicações são CC BY-SA 4.0.
- Para vê-lo trabalhar: o README traz os
curl. O fornecedor de estoque de exemplo é uma pasta com dois arquivos JSON, servida comjwebserver, que o JDK já traz. O banco é H2, em memória: o mais simples que roda de primeira; os dados se apagam ao desligar. A saúde e as métricas, na porta 9000. - Versões: Java 25 com Temurin 25.0.5+8. Quarkus 3.40.1.2: a 3.40 é a versão de suporte longo mais recente do Quarkus [13], e uma versão de suporte longo é mantida por 12 meses, com uma nova a cada seis [12]. Maven pelo Wrapper. GraalVM CE
25.5.5.0+3-graalce, só para o nativo. Foi testado no macOS arm64. No Linux ainda não: o CI está escrito para Ubuntu e macOS, e roda quando o repositório público existir. - Curso de Java da Hábil: se os
record, o Maven ou os testes com JUnit forem novidade, comece por ali: Curso de Java. E se a entrega 5 ainda não foi lida, leia-a primeiro: esta dá por sabidos os papéis do restaurante.
Escrevo a partir do que vemos todos os dias na Hábil, onde construímos sistemas para bancos, seguradoras e empresas no México. Se no trabalho ou na faculdade aparecer um repositório em que ninguém sabe onde mexer, vamos conversar: habil.mx
O que a Hábil faz?
Ensinamos a programar com o mesmo que usamos para construir: código testado, explicado e aberto.
Esta série nasce do mesmo lugar que os nossos cursos. O Curso de Java ensina o Java de hoje: tipos que expressam o modelo, testes, concorrência e um programa terminado, empacotado em um JAR, e o publicamos aberto, com licença Creative Commons; a lição 3 explica os record e a lição 6 o projeto com Maven, a mesma base que o template deste artigo usa. E no catálogo há mais cursos de programação, gratuitos e com código testado e explicado passo a passo.
Veja o Curso de Java e o catálogo de Cursos de programação.
Se a equipe herdar um sistema em que ninguém sabe onde mexer, ou precisar construir um que possa continuar sendo mantido, também fazemos isso: veja Construir um sistema sob medida. Peça a primeira conversa, sem custo. Nela avaliamos se convém configurar o que a equipe já tem, usar um produto ou construir, e o que ela receberia em cada caso. Escreva para nós pelo WhatsApp.
Fontes consultadas em 18 de novembro de 2026. As citações em inglês são reproduzidas tal como estão.
Referências
- 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 testes de 21 de abril de 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» e «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» (referência do 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 do Quarkus, 6 de julho de 2023. https://quarkus.io/blog/lts-releases/
- G. Smet, «Quarkus 3.40 LTS - new LTS version», blog do Quarkus, 30 de setembro de 2026. https://quarkus.io/blog/quarkus-3-40-released/
- Eclipse Foundation, «Jakarta RESTful Web Services 3.1», conversão 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 e S. Dalal, «RFC 9457: Problem Details for HTTP APIs», IETF, julho 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
A operação da empresa enfrenta esses desafios?
Prefere e-mail? Escreva para hola@habil.mx