Episódio 03: Domínio e Veículo — Christian Mulato Dev Blog

A API ganha assunto

Com o projeto criado, chegamos à parte em que a aplicação deixa de ser só dependências e passa a falar a língua do negócio. No teste da recolocação, isso é onde muitos candidatos ou brilham ou expõem acoplamento.

Na visão geral, o exterior só vê JSON; por baixo, o enunciado exige modelo interno coerente antes de persistir:

Visão geral

Cliente API API de veículos Regras do enunciado
(campos, validações)

O “mundo exterior” só enxerga JSON; o PDF exige que o modelo interno seja coerente antes de persistir.

O problema por trás da etapa

O sistema deve trabalhar com cadastro de veículos. Campos obrigatórios: id, descrição, marca e modelo; opcionais: opcionais e valor. Validações com Jakarta Bean Validation. A primeira escolha é tratar Veículo como centro da linguagem — não apenas linha de tabela, mas conceito que a API manipula, persiste, valida e devolve.

Em Spring Boot tradicional, a entidade pode ser anotada com JPA; o equilíbrio em teste prático é separar responsabilidades sem virar arquitetura acadêmica pesada. O essencial é que regras não fiquem no controller e o modelo seja fácil de entender.

Nos blocos de execução, domínio e dados ainda partilham o mesmo processo — a fronteira é pacote e disciplina, não rede:

O que corre na máquina

Spring Boot
(camadas domain + demais) H2
(ainda vazio ou mapeado)

O domínio vive no mesmo processo; a fronteira é disciplina de pacotes, não rede.

A decisão técnica

A entidade reflete descrição, marca, modelo, opcionais e valor. Marca como enum comunica decisão de modelagem, melhora documentação e reduz erro de digitação. Validações: @NotBlank, @NotNull, @Positive, @Size onde couber — contrato na borda, regras contextuais na aplicação.

DTOs CriarVeiculoRequest, AtualizarVeiculoRequest e VeiculoResponse evitam expor a entidade crua e controlam o contrato HTTP. Contratos de repositório no domínio ou aplicação, com implementação na infra, reforçam o mapa em camadas pedido pelo PDF.

As decisões traduzem-se em blocos técnicos — borda HTTP, núcleo de negócio, validação e contrato de persistência:

Domínio versus borda

DTOs Web
request / response Domínio
Veículo, Marca Validação
Bean Validation Contrato persistência
interface repositório

DTOs ficam na borda HTTP; entidade e enum falam a língua do cadastro de veículos; validação não “vaza” para o controller como lógica procedural.

Implementando com critério

Se amanhã surgirem campos técnicos (data de criação, versão), a API não precisa expô-los automaticamente. DTOs funcionam como fronteira. A pergunta guia: se eu removesse a API HTTP, ainda entenderia o que é um veículo no sistema? Se sim, o domínio está no caminho certo.

Na organização do código, tipos e nomes estáveis são o que o avaliador abre primeiro no pacote domain:

Tipos centrais no código

Veiculo
entidade / modelo Marca
enum CriarVeiculoRequest
+ atualizar / response VeiculoRepository
interface

Abriu o pacote domain e reconhece o problema sem ler o controller.

Fechamento da etapa

Sem hierarquia de value objects desnecessária: o PDF valoriza clareza. Ao final: modelo de Veículo claro, enum de marca, requests/responses definidos e contratos de persistência visíveis. Próximo passo: ligar o domínio a JPA, H2 e Flyway.

Como defender essa etapa

Explique a diferença entre contrato HTTP (DTO), conceito persistido (entidade) e regra de aplicação. O enum de marca é exemplo simples de intenção. Aceitar JPA na entidade em teste pequeno pode ser pragmático; o que não pode é HTTP mandando no modelo.

Reflexão final: Bons nomes não são enfeite — são parte da arquitetura legível para quem avalia em poucos minutos.

Nota: Cenário anonimizado; série de insights técnicos reutilizáveis.

Christian Mulato
Engenheiro Construtor