API de Cadastro · Alcides Oliveira

O problema

Eu queria entender como um serviço Spring Boot se organiza, camada por camada, construindo um a partir de um projeto Spring Boot inicial, sem nada além da estrutura básica. O domínio é pequeno de propósito. Cada pessoa pode ter uma tarefa, e uma tarefa pode ter várias pessoas. O README deixa claro que o projeto foi feito para estudo.

Decisões

Mappers escritos à mão

Escrevi a conversão entre entidade e DTO eu mesmo, sem uma biblioteca como o MapStruct. Dá mais código, mas cada cópia de campo fica à vista. A separação não é completa: cada DTO ainda carrega o tipo da entidade relacionada no vínculo entre pessoa e tarefa.

O Flyway controla o esquema

No começo o Hibernate criava as tabelas (ddl-auto=update) e o Flyway rodava a V2 em cima de um baseline. Antes de adicionar o Docker, escrevi a V1 com o esquema base completo, tirei a configuração de baseline e passei o Hibernate para validate. Assim um banco novo é montado só com SQL versionado, e qualquer diferença entre entidades e tabelas impede a inicialização.

Tipos wrapper para campos que aceitam nulo

Troquei a idade da pessoa de int para Integer e o ID da tarefa de long para Long. Primitivos assumem zero por padrão, o que esconderia um valor ausente; os tipos wrapper aceitam nulo.

O que eu fiz

Dez endpoints de CRUD em Spring Web MVC para criar, listar, buscar, substituir e excluir pessoas e tarefas, com resposta 404 para IDs inexistentes, e mais uma rota de saudação para conferir se o serviço está no ar.

Entidades JPA com @ManyToOne da pessoa para a tarefa e o @OneToMany correspondente na tarefa, com @JsonIgnore na lista de pessoas da tarefa para que a referência circular não quebre a serialização JSON.

Duas migrações SQL no Flyway, uma para as tabelas e a chave estrangeira e outra que adiciona a coluna de profissão, com o Hibernate validando o resultado.

DTOs e classes mapper escritas à mão para as duas entidades, para que os controllers recebam e devolvam DTOs em vez das próprias entidades.

Um Dockerfile em duas etapas (build com Maven, depois execução com JRE) e configuração da conexão com o H2 por variáveis de ambiente.

Como funciona

O código é dividido por funcionalidade em dois pacotes, Persons e Tasks. Cada um tem seu controller, service, repository, DTO, mapper e entidade JPA. A requisição chega ao controller como JSON e vira um DTO. O service passa esse DTO a um mapper, que o converte em entidade, e o repository do Spring Data salva. A leitura faz o caminho inverso: entidade, mapper, DTO, JSON. A atualização substitui o registro inteiro: o service converte o corpo recebido em uma entidade nova, aplica o ID da URL e salva.

Os dados ficam em um banco H2 em memória, com o console web do H2 ativado para consulta. O Flyway monta o esquema na inicialização: a V1 cria as tabelas de pessoas e tarefas, com chave estrangeira da pessoa para a tarefa, e a V2 adiciona a coluna de profissão. O Hibernate roda com ddl-auto=validate: ele confere as entidades contra o esquema migrado e interrompe a inicialização se houver diferença. URL de conexão, usuário e senha vêm de variáveis de ambiente.

Os controllers devolvem ResponseEntity: 201 com uma mensagem que traz o ID novo na criação, 200 em leitura, atualização e exclusão, e 404 com mensagem quando o ID não existe. Um Dockerfile em duas etapas gera o jar com Maven em uma imagem JDK 17 e roda o resultado em uma imagem JRE 17.

Tecnologias

Back-end

Java 17, Spring Boot 4.1.1, Spring Web MVC, Spring Data JPA, Hibernate, Lombok

Dados

H2 (em memória, com o console do H2), Flyway

Infraestrutura

Docker (build em duas etapas, imagens Maven e Eclipse Temurin 17)

Ferramentas

Maven Wrapper, JUnit 5 (via spring-boot-starter-webmvc-test), Spring Boot DevTools