Pular para o conteúdo
Arquitetura e backend19 min

A estrutura de um projeto (6): a cozinha que se monta na véspera

Por · 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, service o cozinheiro, repository a 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 PanacheEntity no projeto. Cada resultado é uma ficha do arquivo que também faz as vezes de despensa.

Neste artigo

  1. O que aconteceu na segunda às 9:12?
  2. O que muda e o que não muda?
  3. O que quer dizer «na véspera»?
  4. O que muda em cada pacote?
  5. Quão rápido ela abre?
  6. As setas continuam para dentro?
  7. Quais são cinco erros frequentes?
  8. Exercício: dá para esconder a ficha no tíquete?
  9. Para levar
  10. O que vem depois?
  11. O template e o curso
  12. O que a Hábil faz?
  13. 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.

O que muda e o que não muda?
PapelNo Spring Boot (entrega 5)No Quarkus (esta entrega)
O garçom, apiPedidoController, ResponseEntityPedidoResource, RestResponse
A despensarepository/ com Spring Data: uma interfacemodel/repository/ com Panache: uma classe
O fornecedor, clientRestClient; tempo limite e nova tentativa na configuraçãoREST Client; @Timeout e @Retry na própria interface
O livro de reclamações, exception@RestControllerAdviceUm ExceptionMapper e a extensão quarkus-http-problem
A saúde:8080/actuator/health:9000/q/health, em outra porta
A instalação do localapplication.ymlapplication.yaml
Quem inicia tudoPedidosApplication, com o mainNingué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 árbol

Por 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/ready

Responde (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.

Quão rápido ela abre?
A mesma API, em…Primeira resposta (mediana de 5)Memória (RSS)As cinco execuções
Spring Boot, JVM2.241 ms437 MiB2181, 2241, 2377, 2301, 2207 ms
Quarkus, JVM1.220 ms270 MiB1515, 1250, 1220, 1145, 1175 ms
Quarkus, nativo46 ms60 MiB150, 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/main

Zero 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.

5. Copiar as anotações do Spring
ErroO que denunciaFonte
1. A ficha que também é a despensagrep -rn 'extends PanacheEntity' src/main[5] · medição
2. Tudo para nativo porque abre rápidoRequisições por segundo, não só a inicialização[2]
3. O nativo que morre no primeiro pedidoUm pedido de verdade, não a saúde[3] · medição
4. Uma chave que não faz nadaUm teste que dependa dessa chavemediçã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.sh

Na 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=CapasTest

test-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.sh

Fica 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.java

Deve 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 --short

A 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.bak

Guarde-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.

  1. Quantas fichas do projeto herdam de PanacheEntity? Cada uma é uma entidade que traz os próprios métodos para se guardar.
  2. Se o projeto usa o nativo, que medida o justificou: a inicialização, a memória ou as requisições por segundo? Ficou escrita?
  3. 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 com jwebserver, 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

  1. Quarkus, «Container First»: «Build Time Processing». https://quarkus.io/container-first/
  2. 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
  3. Quarkus, «Tips for writing native applications». https://quarkus.io/guides/writing-native-applications-tips
  4. Quarkus, «Writing REST Services with Quarkus REST»: «Exception mapping». https://quarkus.io/guides/rest
  5. 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
  6. Quarkus, «Using the REST Client». https://quarkus.io/guides/rest-client
  7. Quarkus, «SmallRye Fault Tolerance». https://quarkus.io/guides/smallrye-fault-tolerance
  8. Quarkus, «SmallRye Health». https://quarkus.io/guides/smallrye-health
  9. Quarkus, «Management interface reference». https://quarkus.io/guides/management-interface-reference
  10. Quarkus, «Contexts and Dependency Injection» (referência do ArC). https://quarkus.io/guides/cdi-reference
  11. Quarkus, «YAML configuration». https://quarkus.io/guides/config-yaml
  12. M. Rydahl Andersen, «Long-Term Support (LTS) for Quarkus», blog do Quarkus, 6 de julho de 2023. https://quarkus.io/blog/lts-releases/
  13. 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/
  14. 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
  15. Quarkiverse, «quarkus-http-problem», GitHub. https://github.com/quarkiverse/quarkus-http-problem
  16. 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
  17. ArchUnit, «ArchUnit User Guide»: «Layer Checks». https://www.archunit.org/userguide/html/000_Index.html
  18. Quarkus, «Virtual thread support reference». https://quarkus.io/guides/virtual-threads
  19. Quarkus, «Quarkus extension for Spring DI API». https://quarkus.io/guides/spring-di
  20. Quarkus, «Micrometer Metrics». https://quarkus.io/guides/telemetry-micrometer
  21. SDKMAN, candidatos de Java para macOS arm64 (25.5.5.0+3-graalce). https://api.sdkman.io/2/candidates/java/darwinarm64/versions/list?installed=
  22. Git, «git-restore». https://git-scm.com/docs/git-restore
  23. Quarkus, «Testing your application». https://quarkus.io/guides/getting-started-testing