A estrutura de um projeto (5): a camada que não fazia nada
Por Dorian Chávez · cofundador e Chief Executive Officer da Hábil ·
Quatro camadas e uma facade que só repassa a chamada. O que vai em cada pacote de uma API Spring Boot, quando a facade sobra e um template que o vigia.
A estrutura de um projeto · entrega 5 de 7 · Java com Spring Boot
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 Spring Boot não exige nenhuma forma de organizar o código [1]. As camadas são uma decisão; aqui vai a do template, com o porquê.
- Cada pacote é um papel de um restaurante:
apié o garçom,serviceo cozinheiro,repositorya despensa. E cada papel tem algo que nunca faz. - A
facade, o chefe de cozinha, se justifica quando coordena dois ou mais. Se o método dela só chama outro, sobra. - Para o Java, o cozinheiro conhecer o garçom não é um erro: compila. Quem detecta é um teste de arquitetura [12].
- Daqui sai um template que roda de primeira, com um script que demonstra essa fronteira ficando vermelho quando deve.
- Para segunda-feira: abra a
facadedo projeto e conte quantos métodos só chamam outro.
Neste artigo
- O que aconteceu na quinta às 16:40?
- O que vai em cada pacote?
- Quando a facade faz falta, e quando não?
- Quais são as três regras?
- Quais são cinco erros frequentes?
- Exercício: dá para fazer o cozinheiro chamar o garçom?
- Para levar
- O que vem depois?
- O template e o curso
- O que a Hábil faz?
- Referências
O que aconteceu na quinta às 16:40?
O Iván acrescentou um campo a uma resposta, mexeu em quatro arquivos e encontrou uma camada que não fazia nada.
Quinta-feira, 16:05. Terceiro andar.
Um mês depois do alias. A primeira API em Java, com Spring Boot: os pedidos de uma loja. A tarefa cabia numa linha: «Que a consulta de um pedido diga também quando ele foi criado».
O projeto tinha sido deixado por outra pessoa. Quatro pastas com nome de camada:
src/main/java/…/pedidos/
api/
facade/
service/
repository/O dado já estava na tabela. Para que chegasse ao JSON, o Iván mexeu em quatro arquivos, um por pasta. Em três copiou o campo de uma classe para outra. No quarto, a facade, parou:
public PedidoResponse buscar(UUID id) {
return service.buscar(id);
}Um método que só chamava outro. Recebia o mesmo e devolvia o mesmo. Olhou os outros métodos da classe: eram seis, e cinco faziam isso.
Quinta-feira, 16:40.
Compilou. Os testes passaram. Antes de subir a mudança, escreveu para a Lucía.
— Quatro arquivos para mover um dado. E uma camada não faz nada: chama a seguinte e pronto. Tiro?
— Quantos esse método chama? — respondeu ela.
— Um. O serviço.
— E o de criar um pedido?
O Iván abriu. Esse era diferente: primeiro perguntava o preço a outro sistema, e depois chamava o serviço.
— Dois.
— Então num o chefe de cozinha sobra, e no outro não.
— Que chefe de cozinha?
— Amanhã a gente almoça no restaurante simples em frente. Repara em quem faz o quê.
O Iván olhou as quatro pastas. Tinha achado que eram quatro passos obrigatórios. Eram quatro ofícios.
O que vai em cada pacote?
O que cabe a um papel de um restaurante, e nada mais. As camadas não são exigência do Spring Boot: são uma decisão.
A documentação do Spring Boot diz isso logo de cara: «Spring Boot does not require any specific code layout to work» [1]. O próprio exemplo dela nem organiza por camadas: põe uma pasta para clientes e outra para pedidos [1]. O que ela recomenda, sim, é onde vai a classe que inicia tudo: «in a root package above other classes» [1]. Desse pacote para baixo o Spring procura os componentes e as entidades.
De onde saem, então, api, service e repository? De um costume que o Spring leva nas anotações: @Controller, @Service e @Repository existem para as camadas «persistence, service, and presentation» [2]. Na Hábil é prática da casa: um pacote por papel, e as dependências num só sentido. Não é a única forma correta. É uma que cabe num almoço.
O template desta entrega, estructura-java-spring-boot, é a API de pedidos de uma loja. O pacote raiz é mx.habil.pedidos: o domínio ao contrário e o nome da aplicação [1].
estructura-java-spring-boot/
├── pom.xml bibliotecas y construcción
├── mvnw · .mvn/ el Maven del proyecto
├── Dockerfile la imagen
├── docs/ARCHITECTURE.md las capas y las decisiones
├── herramientas/probar-frontera.sh
├── src/main/java/mx/habil/pedidos/
│ ├── PedidosApplication.java aquí arranca todo
│ ├── api/ el mesero
│ ├── facade/ el jefe de cocina
│ ├── service/ el cocinero
│ ├── repository/ la despensa
│ ├── client/ el proveedor de afuera
│ ├── model/ los papeles que pasan de mano en mano
│ │ ├── request/ la comanda
│ │ ├── response/ el ticket
│ │ ├── entity/ la ficha del archivo
│ │ └── vo/ las medidas exactas
│ ├── mapper/ el que pasa en limpio
│ ├── config/ la instalación del local
│ ├── exception/ el libro de quejas
│ ├── observability/ las cámaras y la bitácora
│ └── utils/ el cajón de herramientas
├── src/main/resources/application.yml
└── src/test/java/mx/habil/pedidos/ el mismo árbolsrc/main e src/test são a organização padrão do Maven, a ferramenta que constrói o projeto: serve para que quem conhece um projeto possa «immediately feel at home in another» [14]. mvnw é o Maven Wrapper: baixa a versão do Maven que o projeto declara, e ninguém a instala à mão [15].
Vamos papel por papel. Cada um traz o exemplo do template e uma linha: o que nunca vai ali.
Quem atende?
api, o garçom. Recebe a comanda, confere se veio bem preenchida e a passa adiante. Não cozinha.
@PostMapping
public ResponseEntity<PedidoResponse> crear(@Valid @RequestBody CrearPedidoRequest comanda) {
PedidoResponse creado = facade.crear(comanda);
return ResponseEntity.created(URI.create("/v1/pedidos/" + creado.id())).body(creado);
}Tudo o que é HTTP vive aqui: a rota, o verbo, o 201. @Valid é a conferência: se a comanda vem mal preenchida, o Spring lança MethodArgumentNotValidException [5] e a cozinha nem fica sabendo. Nunca vai aqui: uma regra de negócio. Um if sobre um dado do pedido é do cozinheiro.
service, o cozinheiro. Aqui vivem as regras. O template tem duas: não se aceita um pedido se faltar uma peça, e o total é preço vezes quantidade.
if (linea.cantidad() > linea.existencias()) {
throw new PedidosException(CodigoError.SIN_EXISTENCIAS,
"De %s se pidieron %d y hay %d".formatted(linea.sku(), linea.cantidad(), linea.existencias()));
}
total = total.mas(linea.importe());Nunca vai aqui: HTTP nem JSON. O cozinheiro não sabe se o pedido chegou por um app ou por telefone; por isso os testes dele rodam sem servidor e sem banco de dados.
repository, a despensa. Guarda e traz.
public interface PedidoRepository extends JpaRepository<PedidoEntity, UUID> {
}É a interface inteira. O Spring Data se encarrega de «creating Repository implementations directly from interfaces» [7]. Nunca vai aqui: uma decisão. Se um pedido pode ser guardado, quem diz é o cozinheiro.
client, o fornecedor de fora. Outro sistema, em outra máquina. No template é o estoque: quantas peças há e a que preço. É chamado com dois cuidados. Um tempo limite: o application.yml declara um segundo para conectar e dois para ler [8]. E uma nova tentativa, só diante de um erro de rede dos que o Spring chama de ResourceAccessException; um 404 do fornecedor é uma resposta e não se repete. O Spring Framework 7 já traz a nova tentativa no núcleo [9]. Duas novas tentativas são três chamadas: «total attempts = 1 initial attempt + maxRetries attempts» [9]. Nunca vai aqui: uma regra do pedido. Nem uma chamada sem tempo limite.
facade, o chefe de cozinha. Coordena. É a pergunta do Iván, e tem uma seção própria.
Que papéis passam de mão em mão?
request é a comanda, response o tíquete e entity a ficha do arquivo. Três papéis, ainda que digam quase o mesmo.
public record CrearPedidoRequest(
@NotBlank @Email @Size(max = 254) String correo,
@NotEmpty @Size(max = 20) List<@Valid @NotNull Linea> lineas) {A comanda e o tíquete são record: classes que só carregam dados, com campos finais [16]. As anotações são do Jakarta Validation [6]. A comanda não traz preço: o preço quem põe é o fornecedor, não o cliente. O tíquete não traz o e-mail: ninguém pediu. A ficha, PedidoEntity, tem a forma da tabela, e é uma classe normal porque a especificação do JPA diz que um record «may not be designated as an entity» [17]. Nunca: a ficha sair pela porta. O garçom entrega o tíquete.
E os outros pacotes?
vo, a medida exata. vo quer dizer value object, objeto de valor: é reconhecido pelo que vale, não por um id; dois Dinero de 100 centavos são a mesma quantia. Dinero não é um long solto: é uma quantia em centavos que nunca é negativa. Se existe, já é válido, e ninguém volta a conferir. O mesmo com Correo. Nunca vai aqui: algo do Spring ou de outra camada.
mapper, quem passa a limpo. Copia da ficha para o tíquete, campo por campo. Nunca vai aqui: um if que decida algo.
config, a instalação do local. O relógio, o telefone para chamar o fornecedor, quantas vezes se tenta de novo. Monta-se uma vez, ao abrir. Nunca vai aqui: regras nem rotas.
exception, o livro de reclamações. Tudo o que pode dar errado tem um código num catálogo, e um único lugar monta a resposta. A forma não é nossa: é o Problem Details, o RFC 9457, que existe «to avoid the need to define new error response formats for HTTP APIs» [4], e o Spring já o traz [3]. Medido no template, pedindo quatro canecas quando há três:
{"detail":"De TAZA-01 se pidieron 4 y hay 3","instance":"/v1/pedidos","status":409,
"title":"No hay existencias suficientes",
"type":"https://pedidos.example/errors/sin_existencias","error_code":"SIN_EXISTENCIAS"}Nunca vai aqui: um formato de erro próprio.
observability, as câmeras e o registro. Cada requisição recebe um número, que sai em cada linha do registro e volta ao cliente em X-Request-ID. Nunca vai aqui: um dado pessoal às claras. Medido: pedido f6bd398a-… recibido de a***@tienda.mx por $424.00.
utils, a gaveta de ferramentas. Mascara.correo tapou esse e-mail. Nunca vai aqui: algo que saiba o que é um pedido. Se sabe, o lugar dele é outro pacote.
Que caminho um pedido segue?
Para dentro, da porta até a despensa; e pelo atalho quando não há nada para coordenar.
POST /v1/pedidos GET /v1/pedidos/{id}
│ │
▼ ▼
api (mesero) revisa la comanda api (mesero)
│ │
▼ │ el atajo: lo atiende
facade (jefe de cocina) │ un solo servicio
├──► client (proveedor) ¿hay? │
▼ ▼
service (cocinero) las reglas ◄──────────────┘
│
▼
repository (despensa) guarda la fichaNa volta, a ficha é passada a limpo e sai o tíquete.
Quando a facade faz falta, e quando não?
Sim, quando coordena dois ou mais serviços ou clientes. Não, quando o método dela só chama outro.
Sexta-feira, 14:10. O restaurante simples em frente.
A Lucía pediu o prato do dia. O Iván, só um suco de hibisco. O garçom deixou a comanda do prato do dia no balcão da cozinha, e uma mulher a leu em voz alta: a sopa de um lado, o ensopado do outro, que saíssem juntos. O suco ele pediu direto a quem o servia.
— Aí está — disse a Lucía. — Para o prato do dia intervêm dois, e alguém tem que dizer a ordem. Para o suco, não.
No template, criar um pedido é o prato do dia. Intervêm o fornecedor e o cozinheiro, nessa ordem:
public PedidoResponse crear(CrearPedidoRequest comanda) {
List<LineaCotizada> cotizadas = new ArrayList<>();
for (CrearPedidoRequest.Linea linea : comanda.lineas()) {
InventarioClient.Producto producto = inventario.consultar(linea.sku())
.orElseThrow(() -> new PedidosException(CodigoError.PRODUCTO_NO_EXISTE,
"No hay un producto con el sku " + linea.sku()));
cotizadas.add(new LineaCotizada(linea.sku(), linea.cantidad(), producto.existencias(),
new Dinero(producto.precioCentavos())));
}
PedidoEntity pedido = pedidos.crear(new Correo(comanda.correo()), cotizadas);
return mapper.aResponse(pedido);
}Pergunta, passa e entrega. Não calcula nem decide: isso é do cozinheiro. Nunca vai aqui: um cálculo, uma regra de negócio, uma consulta direta ao banco, nem um método que só repasse a chamada a um único serviço.
Consultar um pedido é o suco. Um único serviço atende, e o garçom vai direto:
@GetMapping("/{id}")
public PedidoResponse buscar(@PathVariable UUID id) {
return mapper.aResponse(service.buscar(id));
}Quanto custa uma facade que sobra? Um arquivo a mais em cada mudança: os quatro do Iván. E no template nenhum teste a denuncia, porque as setas ficam certas. Decide-se lendo: quantos este método coordena?
Na segunda-feira, o Iván apagou cinco métodos. A facade ficou com um.
Quais são as três regras?
Cada um na própria função; as setas só apontam para dentro; e o que entra, o que se guarda e o que sai são coisas diferentes.
- Cada um na própria função. Quando não se sabe onde vai uma linha, pergunta-se de quem é o trabalho.
- As setas só apontam para dentro.
api → facade → service → repositoryouclient. O cozinheiro nunca chama o garçom. - O que entra, o que se guarda e o que sai são coisas diferentes.
request,entityeresponse, ainda que hoje se pareçam.
A terceira nos mordeu ao testar o template. No macOS, os 71 testes daquele momento passavam. No Linux, um falhou: o pedido recém-criado dizia "creado_en":"2026-11-17T21:30:32.024605370Z", e o mesmo pedido, consultado logo depois, "2026-11-17T21:30:32.024605Z". O que saiu e o que se guardou já não eram o mesmo: o banco tinha guardado menos casas decimais. O conserto foi uma regra do cozinheiro, cortar a hora no milissegundo, com o teste correspondente. Por isso hoje são 72.
Como saber que as setas apontam para dentro?
Porque um teste lê as classes compiladas e falha quando uma aponta para fora. E porque um script comprova que esse teste sabe falhar.
Para o Java, as classes de um mesmo projeto podem se importar entre si. Se o cozinheiro importa o garçom, compila. Quem vigia a regra é o CapasTest, escrito com ArchUnit, uma biblioteca «for checking the architecture of your Java code» que trabalha «analyzing given Java bytecode» [12]: revisa o compilado, não o texto. Entende o Java 25 desde a versão 1.4.1 [13]; o template usa a 1.5.1.
.whereLayer("api").mayNotBeAccessedByAnyLayer()
.whereLayer("facade").mayOnlyBeAccessedByLayers("api")
.whereLayer("service").mayOnlyBeAccessedByLayers("api", "facade")
.whereLayer("repository").mayOnlyBeAccessedByLayers("service")
.whereLayer("client").mayOnlyBeAccessedByLayers("facade", "service")Mas um teste que sempre passa não demonstra nada. herramientas/probar-frontera.sh trabalha numa cópia temporária e roda o CapasTest duas vezes:
- Controle, com o projeto tal como está. Tem que rodar e passar. Se não, o experimento está mal montado, ou o projeto já traz uma seta para fora, e o script para em vermelho.
- Violação. Planta-se no
PedidoServiceum método que recebe umPedidoController. Tem que compilar, e oCapasTesttem que falhar, numa única regra e pela razão exata.
Esta é a saída real:
1/2 control: el proyecto tal como está; el cocinero (service) no conoce al mesero (api)
✅ compiló y CapasTest pasó: 4 reglas, 0 fallas
2/2 violación: se siembra en PedidoService un método que recibe un PedidoController
✅ compiló sin una queja: para Java, que el cocinero conozca al mesero no es un error
Method <mx.habil.pedidos.service.PedidoService.avisar(mx.habil.pedidos.api.PedidoController)> has parameter of type <mx.habil.pedidos.api.PedidoController>
✅ CapasTest falló en una sola regla, lasFlechasSoloVanHaciaAdentro: las flechas solo van hacia adentro
✅ frontera: se sostieneQuebramos de sete maneiras, e as sete saíram em vermelho. Três dizem muito: com a regra apagada do CapasTest, ❌ PASÓ; com uma violação que não compila, diz que isso «no demuestra la frontera»; com o Java 21 em vez do 25, para no controle.
Quais são cinco erros frequentes?
Os cinco saem da mesma coisa: um papel fazendo o trabalho de outro.
1. O garçom que cozinha
Uma regra de negócio no controlador.
Funciona, e se nota depois: para testar a regra é preciso subir a parte web. O teste do controlador do template usa @WebMvcTest, que deixa de fora os demais componentes: «Regular @Component and @ConfigurationProperties beans are not scanned» [22]. O do serviço roda com Java e nada mais.
2. O chefe de cozinha que só passa o prato
Uma facade cujo método só chama outro.
É o do Iván. O teste de arquitetura não o marca: as setas estão certas. Quem denuncia é a contagem: quantos serviços ou clientes cada método coordena?
3. Entregar a ficha do arquivo
O controlador devolve a entity.
Compila, e responde demais. Medido no template, mudando um único método: de 72 testes, falham 3. Um diz sem rodeios:
Expected no value at JSON path "$.correo" but found: 'ana@tienda.mx'O e-mail do cliente saiu numa resposta que nunca deveria tê-lo levado. Um dos três é o CapasTest: pergunta se alguma classe de api depende de uma entity, não que tipo um método devolve. Por isso também fica vermelho se a ficha vai escondida num List<PedidoEntity> ou num ResponseEntity<PedidoEntity>; medido com os dois.
4. Chamar o fornecedor sem tempo limite
Se o fornecedor trava, a API trava junto.
No template, o tempo limite é uma linha do application.yml [8]. Medido: sem essa linha, o teste que espera um 504 fica vermelho. E atenção ao que se tenta de novo: um «não existe» do fornecedor é uma resposta. O template só repete diante de um erro de rede, e pode fazê-lo porque a consulta é um GET: perguntar duas vezes quantas canecas há não muda nada. Uma escrita, como cobrar, não se repete assim: primeiro é preciso torná-la idempotente, que repeti-la dê o mesmo que fazê-la uma vez.
5. Copiar os import de um tutorial velho
O Spring Boot 4 usa o Jackson 3 de saída, e as classes dele mudaram de pacote.
O Jackson é a biblioteca que converte objetos em JSON. No Spring Boot 4, a versão 3 é «the preferred and default library» [10]; a 2 continua de forma temporária, para migrar, e o template não a usa. E o guia de migração avisa: os pacotes passam de com.fasterxml.jackson para tools.jackson, com uma exceção, as anotações, que continuam em com.fasterxml.jackson.annotation [11]. Medido no template, com um import dos antigos:
package com.fasterxml.jackson.databind does not exist| Erro | O que o denuncia | Fonte |
|---|---|---|
| 1. O garçom que cozinha | Um if sobre um dado do pedido em api | [2][22] |
| 2. A facade que só passa o prato | Um método que só chama outro | regra do template |
| 3. Entregar a ficha | Um dado a mais no JSON | medição |
| 4. Sem tempo limite | Uma resposta lenta que chega, sim | [8][9] |
5. import de tutorial velho | package … does not exist | [10][11] |
Exercício: dá para fazer o cozinheiro chamar o garçom?
O exercício planta uma seta para fora, mostra que o Java a aceita e deixa ver como o teste e o script avisam.
É preciso o Java 25 (java -version), Git, bash e curl; uns 25 minutos. O Maven, não: o projeto o traz.
- No Linux e no macOS, instale o Java com o SDKMAN [23]. No Linux, antes, fazem falta
curl,zipeunzip(medido no Ubuntu 24.04, a base do Linux Mint 22 [28]):
sudo apt install curl zip unzip
curl -s "https://get.sdkman.io" | bashAbra outro terminal, entre na pasta do template (a do passo 1) e rode sdk env install. Abra mais um terminal (naquele em que instalou, o java ainda não é encontrado; medido) e, nessa pasta, rode sdk env. A lição 1 do curso de Java explica passo a passo. - No Windows, use o WSL.
Passo 1. Clone e confira que tudo está verde.
git clone https://github.com/HabilMX/estructura-java-spring-boot
cd estructura-java-spring-boot
./mvnw verify
bash herramientas/probar-frontera.shNa primeira vez demora: baixa o Maven e as bibliotecas. Deve aparecer Tests run: 72, 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 passo seguinte acrescenta ao cozinheiro, PedidoService, um método que recebe o garçom, PedidoController. Anote: compila? O que diz o CapasTest? E o script da fronteira?
Passo 3. Plante a seta. A primeira linha tira a última chave da classe e deixa uma cópia .bak; a segunda acrescenta o método e fecha a classe. Servem igual no Linux e no macOS.
sed -i.bak '$d' src/main/java/mx/habil/pedidos/service/PedidoService.java
printf ' public void avisar(mx.habil.pedidos.api.PedidoController mesero) {\n }\n}\n' \
>> src/main/java/mx/habil/pedidos/service/PedidoService.java
./mvnw -q test-compile
./mvnw -q test -Dtest=CapasTesttest-compile termina 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.service.PedidoService.avisar(mx.habil.pedidos.api.PedidoController)> has parameter of type <mx.habil.pedidos.api.PedidoController> in (PedidoService.java:0)Passo 4. Pergunte ao script.
bash herramientas/probar-frontera.shFica vermelho, sem chegar ao segundo passo:
❌ 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. O exercício mudou um arquivo. Antes de desfazer, veja o que mudou nele:
git diff -- src/main/java/mx/habil/pedidos/service/PedidoService.javaDevem aparecer duas linhas novas: o método avisar e a chave dele. Se aparecer algo mais, não é do exercício: guarde antes de seguir. Se só estiver o que é do exercício, restaure esse arquivo. git restore só mexe nos caminhos indicados [24]:
git restore src/main/java/mx/habil/pedidos/service/PedidoService.java
bash herramientas/probar-frontera.sh
git status --shortA fronteira volta ao verde, e o git status mostra o que resta: a cópia que o sed fez.
?? src/main/java/mx/habil/pedidos/service/PedidoService.java.bakGuarde-a até ter certeza de que não faz falta. Depois apague com rm -i, que pergunta antes. Não use um comando que limpe a pasta inteira: levaria junto as anotações que estiverem ali.
Como saber que deu certo: foram seis execuções e três desfechos. Verde, quatro vezes: as duas do passo 1, o 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 o PedidoService.java termine numa única chave }.
Para ir mais longe (opcional): faça o garçom entregar a ficha. No PedidoController, mude o método buscar para que devolva mx.habil.pedidos.model.entity.PedidoEntity e retorne service.buscar(id) sem passar pelo mapper. Antes, preveja: compila? Quantos testes falham? Resposta: compila, e ./mvnw -q test termina com Tests run: 72, Failures: 3 (medido). Desfaça igual ao passo 5: git diff desse arquivo, e git restore com o caminho dele.
Para levar
Três perguntas para fazer ao repositório esta semana.
- Quantos métodos da
facadedo projeto só chamam outro? Cada um é um arquivo a mais na próxima mudança. - Algum controlador devolve uma
entity? Se sim, que campo da tabela está saindo sem que ninguém o tenha pedido? - O que avisa se amanhã um serviço importar um controlador? Se a resposta for «a revisão de código», depende de alguém ver.
O que vem depois?
O restaurante não depende da marca do fogão.
Duas semanas depois, passaram ao Iván outra API de pedidos. Ele abriu o projeto e reconheceu as pastas: api, facade, service, repository. Procurou @RestController para começar pelo garçom.
Não havia nenhum.
Também não estava a classe que inicia a aplicação. Nem um único import do Spring. E mesmo assim, as camadas eram as mesmas e as setas apontavam para dentro. No domingo, 6 de dezembro, na entrega 6: mesmo restaurante, outra cozinha mais rápida. As mesmas camadas em Quarkus, o que muda em cada pacote e quão rápida ela é, medida.
O template e o curso
- Template: github.com/HabilMX/estructura-java-spring-boot. Usa-se como template do GitHub ou se clona [26]. O README explica cada pacote com o «nunca» correspondente, o caminho de um pedido, 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, um servidor mínimo que o JDK já traz [25]. O banco é H2, em memória [7]: o mais simples que roda de primeira; os dados se apagam ao desligar. A saúde responde em/actuator/health, e do Actuator não se publica mais nada [21]. - Versões: Java 25, a versão de suporte longo (LTS) vigente [20], com Temurin 25.0.5+8. Spring Boot 4.1.2, a vigente em 17 de novembro [19], que aceita do Java 17 ao Java 27 [18]; o template fica no 25 e não deixa construir com outro. Maven 3.9.16, pelo Wrapper [15]. ArchUnit 1.5.1 [13]. Foi testado no macOS arm64 (também com o
/bin/bashdo sistema) e no Linux arm64 (contêinerubuntu:24.04). O Linux x86-64 ainda não foi testado. O CI está escrito para Ubuntu e macOS com Temurin 25, a cada mudança e toda segunda-feira; se o repositório público passar 60 dias sem atividade, o GitHub desliga a execução das segundas [27]. - Curso de Java da Hábil: se os
record, o Maven ou os testes com JUnit forem novidade, comece por ali: Curso de Java · Lição 3, records · Lição 6, um projeto com Maven.
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 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 17 de novembro de 2026. As citações em inglês são reproduzidas tal como estão.
Referências
- Spring Boot 4.1.2, «Structuring Your Code». https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html
- Spring Framework, «Classpath Scanning and Managed Components»:
@Componente as anotações de estereótipo. https://docs.spring.io/spring-framework/reference/core/beans/classpath-scanning.html - Spring Framework, «Error Responses». https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html
- M. Nottingham, E. Wilde e S. Dalal, «RFC 9457: Problem Details for HTTP APIs», IETF, julho de 2023. https://www.rfc-editor.org/rfc/rfc9457.html
- Spring Framework, «Validation» (Spring MVC, métodos de controlador). https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-controller/ann-validation.html
- Eclipse Foundation, «Jakarta Validation 3.1». https://jakarta.ee/specifications/bean-validation/3.1/
- Spring Boot 4.1.2, «SQL Databases»: «Embedded Database Support» e os repositórios do Spring Data. https://docs.spring.io/spring-boot/reference/data/sql.html
- Spring Boot 4.1.2, «REST Clients»:
spring.http.clients.connect-timeouteread-timeout. https://docs.spring.io/spring-boot/reference/io/rest-client.html - Spring Framework, «Resilience Features». https://docs.spring.io/spring-framework/reference/core/resilience.html
- Spring Boot 4.1.2, «JSON» («Jackson 3 is the preferred and default library»). https://docs.spring.io/spring-boot/reference/features/json.html
- Spring Boot, «Spring Boot 4.0 Migration Guide»: «Upgrading Jackson». https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
- ArchUnit, «ArchUnit User Guide»: «Introduction» e «Layer Checks». https://www.archunit.org/userguide/html/000_Index.html
- TNG, «ArchUnit», versões 1.4.1 («Support Java 25») e 1.5.1, GitHub. https://github.com/TNG/ArchUnit/releases
- Apache Maven, «Introduction to the Standard Directory Layout». https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html
- Apache Maven, «Maven Wrapper». https://maven.apache.org/tools/wrapper/
- Oracle, «Record Classes», Java Language Updates, Java SE 25. https://docs.oracle.com/en/java/javase/25/language/records.html
- Eclipse Foundation, «Jakarta Persistence 3.2», seção «The Entity Class». https://jakarta.ee/specifications/persistence/3.2/jakarta-persistence-spec-3.2
- Spring Boot 4.1.2, «System Requirements». https://docs.spring.io/spring-boot/system-requirements.html
- Spring, versões do Spring Boot (API do spring.io): 4.1.2, a vigente. https://api.spring.io/projects/spring-boot/releases
- Eclipse Adoptium, «Support» («Java 25 (LTS)»). https://adoptium.net/support/
- Spring Boot 4.1.2, «Endpoints» (Actuator). https://docs.spring.io/spring-boot/reference/actuator/endpoints.html
- Spring Boot 4.1.2, «Testing Spring Boot Applications»:
@WebMvcTest. https://docs.spring.io/spring-boot/reference/testing/spring-boot-applications.html - SDKMAN, «Usage»:
sdk env. https://sdkman.io/usage/ - Git, «git-restore» («Restore specified paths in the working tree»). https://git-scm.com/docs/git-restore
- Oracle, «The jwebserver Command», Java SE 25. https://docs.oracle.com/en/java/javase/25/docs/specs/man/jwebserver.html
- GitHub Docs, «Creating a template repository». https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository
- GitHub Docs, «Disabling and enabling a workflow». https://docs.github.com/en/actions/how-tos/manage-workflow-runs/disable-and-enable-workflows
- Linux Mint, «Linux Mint 22 Release Notes» («Linux Mint 22.x is based on Ubuntu 24.04»), linuxmint.com. https://www.linuxmint.com/rel_wilma.php
A operação da empresa enfrenta esses desafios?
Prefere e-mail? Escreva para hola@habil.mx