Hands-on 1 — CRUD

The goal

• A CRUD API for accounts — here Create, Read and Delete (no update).
• Built with Spring Boot, following Domain-Driven Design and Clean Architecture.
• Persisted in PostgreSQL, running in Docker Compose.
• It is the template every other microservice of the course will copy.

Two modules

Clean architecture: one object per layer

Request → Controller/Resource → Service → Repository → Database

On the way back: AccountModel → Account → AccountOut. AccountParser and AccountModel do the translations.

Step 1 — Controller: the contract

@FeignClient(name = "account", url = "http://account:8080")
public interface AccountController {
    @PostMapping("/accounts")
    ResponseEntity<Void> create(@RequestBody AccountIn in);
    @GetMapping("/accounts")
    ResponseEntity<List<AccountOut>> findAll();
    @DeleteMapping("/accounts/{id}")
    ResponseEntity<Void> delete(@PathVariable String id);
    @GetMapping("/accounts/health-check")
    ResponseEntity<Void> healthCheck();
    @GetMapping("/accounts/{id}")
    ResponseEntity<AccountOut> findById(@PathVariable String id);
}

DTOs are Lombok @Builder records with @Accessors(fluent = true): AccountIn(name, email, password) and AccountOut(id, name, email) — the password never goes out.

Project setup

Each module is its own git repository, added as a submodule:

git submodule add <repository_url> api/account
git submodule add <repository_url> api/account-service

Step 2 — Service: make it answer

AccountResource implements AccountController; at first only health-check is real.

@Controller
public class AccountResource implements AccountController {
    @Override
    public ResponseEntity<Void> healthCheck() {
        return ResponseEntity.ok().build();
    }
    // create, findAll, delete, findById: filled in later
}

mvn clean package spring-boot:run
curl -X GET http://localhost:8080/accounts/health-check   # 200 OK

Step 3 — Containerization

FROM eclipse-temurin:25
VOLUME /tmp
COPY target/*.jar /app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

services:
  db:
    image: postgres:17
    volumes:
      - ${VOLUME_DB}:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: ${DB_USER:-store}
  account:
    build:
      context: ./account-service
    depends_on:
      - db

docker compose up -d --build · docker compose ps -a — the services live in a trusted layer.

Step 4 — Repository: ORM with JPA

@Entity
@Table(name = "accounts")
public class AccountModel {
    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    private String id;
    private String name;
    private String email;
    @Column(name = "hash_password")
    private String hashPassword;
}

public interface AccountRepository
    extends CrudRepository<AccountModel, String> {
    List<AccountModel> findAll();
}

The finished endpoints

create builds the Location header with ServletUriComponentsBuilder.fromCurrentRequest().path("/{id}"); an unknown id in findById throws ResponseStatusException(NOT_FOUND).

Run and verify

compose.yaml passes DATABASE_HOST: db, DATABASE_PORT: 5432, DATABASE_DB, DATABASE_USERNAME, DATABASE_PASSWORD to account.

docker compose up --build                     # build images and start db + account
docker compose ps -a                          # container names and status
docker compose logs -f account                # look for the Flyway migrations
docker compose exec db psql -U store -d store # open psql in the db container

Inside psql (it runs in the db container, not in account):

• \dn lists the schemas — accounts must be there.
• \dt *.* lists the tables — accounts.accounts must be there.

Common pitfalls

• The Dockerfile copies target/*.jar: package before docker compose up --build.
• Inside Compose, services talk by hostname (db, account), not localhost.
• A migration already applied is history: change the schema with a new V…__…sql script.
• Keep the password out of AccountOut — the output DTO is the public face of the service.

Takeaways

1. A microservice = an interface module (account) + an implementation (account-service).
2. Clean Architecture: DTO → entity → model, with parsers between layers.
3. @FeignClient on the interface makes the contract reusable by other services.
4. JPA maps AccountModel to a table; CrudRepository gives the CRUD for free.
5. Flyway versions the schema with ordered V…__…sql scripts.
6. Docker Compose runs the service and PostgreSQL together, wired by environment variables.
7. Store a hash, never the password — and never return it.