Pular para o conteúdo
Arquitetura e backend16 min

A estrutura de um projeto (5): a camada que não fazia nada

Por · 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, service o cozinheiro, repository a 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 facade do projeto e conte quantos métodos só chamam outro.

Neste artigo

  1. O que aconteceu na quinta às 16:40?
  2. O que vai em cada pacote?
  3. Quando a facade faz falta, e quando não?
  4. Quais são as três regras?
  5. Quais são cinco erros frequentes?
  6. Exercício: dá para fazer o cozinheiro chamar o garçom?
  7. Para levar
  8. O que vem depois?
  9. O template e o curso
  10. O que a Hábil faz?
  11. 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 árbol

src/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 ficha

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

  1. Cada um na própria função. Quando não se sabe onde vai uma linha, pergunta-se de quem é o trabalho.
  2. As setas só apontam para dentro. api → facade → service → repository ou client. O cozinheiro nunca chama o garçom.
  3. O que entra, o que se guarda e o que sai são coisas diferentes. request, entity e response, 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:

  1. 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.
  2. Violação. Planta-se no PedidoService um método que recebe um PedidoController. Tem que compilar, e o CapasTest tem 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 sostiene

Quebramos 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
5. Copiar os import de um tutorial velho
ErroO que o denunciaFonte
1. O garçom que cozinhaUm if sobre um dado do pedido em api[2][22]
2. A facade que só passa o pratoUm método que só chama outroregra do template
3. Entregar a fichaUm dado a mais no JSONmedição
4. Sem tempo limiteUma resposta lenta que chega, sim[8][9]
5. import de tutorial velhopackage … 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, zip e unzip (medido no Ubuntu 24.04, a base do Linux Mint 22 [28]):
  sudo apt install curl zip unzip
  curl -s "https://get.sdkman.io" | bash

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

Na 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=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.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.sh

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

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

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

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

  1. Quantos métodos da facade do projeto só chamam outro? Cada um é um arquivo a mais na próxima mudança.
  2. Algum controlador devolve uma entity? Se sim, que campo da tabela está saindo sem que ninguém o tenha pedido?
  3. 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 com jwebserver, 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/bash do sistema) e no Linux arm64 (contêiner ubuntu: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

  1. Spring Boot 4.1.2, «Structuring Your Code». https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html
  2. Spring Framework, «Classpath Scanning and Managed Components»: @Component e as anotações de estereótipo. https://docs.spring.io/spring-framework/reference/core/beans/classpath-scanning.html
  3. Spring Framework, «Error Responses». https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html
  4. 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
  5. Spring Framework, «Validation» (Spring MVC, métodos de controlador). https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-controller/ann-validation.html
  6. Eclipse Foundation, «Jakarta Validation 3.1». https://jakarta.ee/specifications/bean-validation/3.1/
  7. 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
  8. Spring Boot 4.1.2, «REST Clients»: spring.http.clients.connect-timeout e read-timeout. https://docs.spring.io/spring-boot/reference/io/rest-client.html
  9. Spring Framework, «Resilience Features». https://docs.spring.io/spring-framework/reference/core/resilience.html
  10. Spring Boot 4.1.2, «JSON» («Jackson 3 is the preferred and default library»). https://docs.spring.io/spring-boot/reference/features/json.html
  11. Spring Boot, «Spring Boot 4.0 Migration Guide»: «Upgrading Jackson». https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
  12. ArchUnit, «ArchUnit User Guide»: «Introduction» e «Layer Checks». https://www.archunit.org/userguide/html/000_Index.html
  13. TNG, «ArchUnit», versões 1.4.1 («Support Java 25») e 1.5.1, GitHub. https://github.com/TNG/ArchUnit/releases
  14. Apache Maven, «Introduction to the Standard Directory Layout». https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html
  15. Apache Maven, «Maven Wrapper». https://maven.apache.org/tools/wrapper/
  16. Oracle, «Record Classes», Java Language Updates, Java SE 25. https://docs.oracle.com/en/java/javase/25/language/records.html
  17. Eclipse Foundation, «Jakarta Persistence 3.2», seção «The Entity Class». https://jakarta.ee/specifications/persistence/3.2/jakarta-persistence-spec-3.2
  18. Spring Boot 4.1.2, «System Requirements». https://docs.spring.io/spring-boot/system-requirements.html
  19. Spring, versões do Spring Boot (API do spring.io): 4.1.2, a vigente. https://api.spring.io/projects/spring-boot/releases
  20. Eclipse Adoptium, «Support» («Java 25 (LTS)»). https://adoptium.net/support/
  21. Spring Boot 4.1.2, «Endpoints» (Actuator). https://docs.spring.io/spring-boot/reference/actuator/endpoints.html
  22. Spring Boot 4.1.2, «Testing Spring Boot Applications»: @WebMvcTest. https://docs.spring.io/spring-boot/reference/testing/spring-boot-applications.html
  23. SDKMAN, «Usage»: sdk env. https://sdkman.io/usage/
  24. Git, «git-restore» («Restore specified paths in the working tree»). https://git-scm.com/docs/git-restore
  25. Oracle, «The jwebserver Command», Java SE 25. https://docs.oracle.com/en/java/javase/25/docs/specs/man/jwebserver.html
  26. GitHub Docs, «Creating a template repository». https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository
  27. GitHub Docs, «Disabling and enabling a workflow». https://docs.github.com/en/actions/how-tos/manage-workflow-runs/disable-and-enable-workflows
  28. 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