Spring Reservation System

What this is

• A small Spring Boot service for reservations (rooms/resources).
• Clean layered design: Controller → Service → Repository → Entity.
• Intended as a starter/prototype or a simple microservice example.

Quick facts

• Language: Java (11+ recommended)
• Framework: Spring Boot (Web, Data JPA, Validation)
• Persistence: JPA / Hibernate (H2 for dev; Postgres/MySQL for prod)
• Convenience: Lombok (IDE plugin recommended)
• Build: Maven (mvnw included)
• Tests: JUnit 5 + Mockito
• Optional: Flyway for migrations, Docker for container builds

Minimal quick start

1. Build:

./mvnw clean package -DskipTests

2. Run:

java -jar target/*.jar

3. Default dev URL:

• http://localhost:8080/api/reservations

Configuration notes

• application.properties (or .yml) holds DB and app config.
• Dev uses in-memory H2 by default; switch datasource to Postgres/MySQL for production and use Flyway/Liquibase migrations.
• Keep secrets/environment-specific values out of the repo (env vars, secret manager, .env, Vault).

Project layout (what to look at)

• com.yourorg.reservation
  • controller — HTTP endpoints, should be thin
  • service — business rules, validations, transactions
  • repository — Spring Data JPA interfaces
  • entity — JPA models
  • dto — request/response shapes
  • config — beans, properties, data source config
  • exception — custom errors and ControllerAdvice

Annotations cheat-sheet (most used)

• App: @SpringBootApplication
• Web: @RestController, @RequestMapping, @GetMapping / @PostMapping / @PutMapping / @DeleteMapping, @RequestBody, @PathVariable
• Service: @Service, @Transactional, @Validated
• Persistence: @Entity, @Table, @Id, @GeneratedValue, @Column, @ManyToOne / @OneToMany / @JoinColumn
• Validation: @Valid, @NotNull, @NotBlank, @Size, @Future
• Lombok: @Data, @Builder, @NoArgsConstructor, @AllArgsConstructor

API conventions (follow these)

• GET /api/reservations — list
• GET /api/reservations/{id} — detail
• POST /api/reservations — create → 201 Created (Location header)
• PUT /api/reservations/{id} — update
• DELETE /api/reservations/{id} — delete → 204 No Content

Error handling

• Use ControllerAdvice + consistent error body: timestamp, status, error, message, path.
• Common statuses: 400 (validation), 404 (not found), 409 (conflict/overlap), 500 (server).

Testing strategy

• Unit tests: JUnit 5 + Mockito for services and utilities.
• Repository tests: @DataJpaTest (H2 or Testcontainers).
• Controller tests: @WebMvcTest + MockMvc for request/response behavior.
• Integration: @SpringBootTest when you need full-context tests (prefer Testcontainers for real DBs).

Docker (simple)

• Build JAR, then a small JDK image that runs it. Use Dockerfile and docker build / run as usual. Keep DB outside container or use compose for DB + app.

Good practices / contribution tips

• Keep controllers thin; put logic in services.
• Use DTOs for API boundaries — do not expose JPA entities directly.
• Validate incoming requests with javax.validation annotations.
• Make small, focused PRs with tests.
• Use a shared formatter and linting rules.
• Document API changes in README or an OpenAPI spec.