Registration API · Alcides Oliveira

The problem

I wanted to learn how a Spring Boot service is put together, layer by layer, by building one on top of a bare Spring Boot starter project. The domain is small on purpose. Each person can hold one task, and a task can have several people. The README states the project was made for study.

Decisions

Mappers written by hand

I wrote the entity and DTO conversion myself instead of using a library like MapStruct. It is more code, but every field copy stays in view. The boundary is partial: each DTO still holds the related entity type for the person-task link.

Flyway owns the schema

At first Hibernate created the tables (ddl-auto=update) and Flyway ran V2 on top of a baseline. Before adding Docker, I wrote V1 with the full base schema, removed the baseline setting, and switched Hibernate to validate, so a fresh database is built from versioned SQL alone and any drift between entities and tables stops startup.

Wrapper types for nullable fields

I switched the person’s age from int to Integer and the task ID from long to Long. Primitives default to zero, which would hide a missing value; the wrapper types let a field be null.

What I built

Ten CRUD endpoints in Spring Web MVC to create, list, fetch, replace, and delete people and tasks, with 404 responses for unknown IDs, plus a greeting route to check the service is up.
JPA entities with a @ManyToOne link from person to task and the matching @OneToMany on the task side, using @JsonIgnore on the task’s list of people so the circular reference does not break JSON serialization.
Two Flyway SQL migrations, one for the tables and foreign key and one that adds the profession column, with Hibernate validating the result.
DTOs and hand-written mapper classes for both entities, so controllers receive and return DTOs instead of the entities themselves.
A two-stage Dockerfile (Maven build, then JRE runtime) and configuration of the H2 connection through environment variables.

How it works

The code is split by feature into two packages, Persons and Tasks. Each one has its own controller, service, repository, DTO, mapper, and JPA entity. A request reaches the controller as JSON and becomes a DTO. The service hands it to a mapper that turns it into an entity, and the Spring Data repository saves it. Reads go the other way: entity, mapper, DTO, JSON. Updates are full replacements: the service maps the submitted body to a new entity, sets the ID from the path, and saves it.

Data lives in an H2 in-memory database, with the H2 web console turned on for inspection. Flyway builds the schema at startup: V1 creates the persons and tasks tables with a foreign key from person to task, and V2 adds a profession column. Hibernate runs with ddl-auto=validate, so it checks the entities against the migrated schema and stops startup if they disagree. The connection URL, username, and password come from environment variables.

Controllers return ResponseEntity: 201 with a message that includes the new ID on create, 200 on reads, updates, and deletes, and 404 with a message when an ID does not exist. A two-stage Dockerfile builds the jar with Maven on a JDK 17 image and runs it on a JRE 17 image.

Built with

Back end: Java 17, Spring Boot 4.1.1, Spring Web MVC, Spring Data JPA, Hibernate, Lombok
Data: H2 (in-memory, with H2 console), Flyway
Infrastructure: Docker (multi-stage, Maven and Eclipse Temurin 17 images)
Tooling: Maven Wrapper, JUnit 5 (via spring-boot-starter-webmvc-test), Spring Boot DevTools