Spring Boot From Scratch

API REST per la gestione di progetti e task — costruita da zero con Spring Boot 3 e Java 21.

Quick Start · API · Tech Stack · Documentazione · Contribuire

---

📖 Indice

• Cos'è
• Dominio applicativo
• Funzionalità
• Tech stack
• Quick Start
• API overview
• Struttura del repository
• Testing
• Documentazione
• Contribuire
• Licenza

---

🧭 Cos'è

Spring Boot From Scratch è un'applicazione Spring Boot 3 didattica ma production-grade che implementa un'API REST per la gestione di progetti e dei loro task. È pensata per:

• studenti e sviluppatori junior–mid che vogliono vedere un'applicazione Spring Boot ben strutturata end-to-end (controller → service → repository, validazione, error handling, persistenza, test);
• team che cercano uno scaffold pulito da cui partire per un nuovo servizio Spring Boot.

Niente magia, niente shortcut: ogni layer è esplicito, i DTO sono immutabili, le regole di dominio vivono nel modello, gli errori sono standardizzati in RFC 7807 Problem Details e i test integrazione girano contro un PostgreSQL reale via Testcontainers.

---

🗂️ Dominio applicativo

Il dominio è gestione di progetti e task:

Project (1) ────< (N) Task

• Project ha name, description, status (ACTIVE / ARCHIVED) e timestamp.
• Task appartiene a un progetto e ha title, description, status (TODO / IN_PROGRESS / DONE), priority (LOW / MEDIUM / HIGH) e dueDate.

Regole di business

• Un progetto archiviato non accetta nuovi task (HTTP 409).
• Le transizioni di stato dei task seguono una state machine controllata:

  TODO ──► IN_PROGRESS ──► DONE
   ▲           │              │
   └───────────┴──────────────┘ (riapertura sempre verso TODO)
  

• Eliminare un progetto cancella in cascata i suoi task.

---

⚡ Funzionalità

	Feature	Descrizione
🧱	Clean Architecture	Package by feature (project/, task/, common/), constructor injection, DTO records immutabili.
🗄️	Persistenza JPA + Flyway	Hibernate 6, migration versionate (V1__init.sql), index, vincoli CHECK lato DB.
✅	Bean Validation	@NotBlank, @Size, enum vincolati, controllati al boundary del controller.
🛡️	Error handling RFC 7807	ProblemDetail standardizzato per 400/404/409/500 con campi custom (field errors, transitions).
🧪	Testing first-class	Unit (JUnit 5 + Mockito) + Integration (Testcontainers + PostgreSQL reale) + slice (MockMvc).
📊	Observability	Actuator + Micrometer + endpoint Prometheus + health check liveness/readiness.
📘	OpenAPI 3.1	Documentazione auto-generata con springdoc, UI Swagger a /swagger-ui.html.
🐳	Docker production-ready	Dockerfile multi-stage con layered JAR, utente non-root, healthcheck.
🔄	CI/CD GitHub Actions	Build & test su PR, deploy docs su GitHub Pages, release con changelog auto, CodeQL, Dependabot.

---

🧱 Tech stack

Categoria	Tecnologie
Linguaggio & runtime	Java 21 (LTS), virtual threads abilitati
Framework	Spring Boot 3.4, Spring Data JPA, Spring Validation
Persistenza	Hibernate 6, PostgreSQL 16, Flyway
Build	Maven 3.9 (wrapper incluso)
Testing	JUnit 5, Mockito, AssertJ, Testcontainers, MockMvc, JaCoCo
Observability	Actuator, Micrometer, Prometheus, Logback
API & Docs	springdoc-openapi 2.x, MkDocs Material, Structurizr (C4)
Container	Docker multi-stage, docker-compose (PostgreSQL + Prometheus)

---

🚀 Quick Start

Opzione A — con Docker Compose (consigliata)

git clone https://github.com/fedcal/Spring-Boot-From-Scratch.git
cd Spring-Boot-From-Scratch
docker compose up --build

L'app è disponibile su http://localhost:8080; Swagger UI su http://localhost:8080/swagger-ui.html; Prometheus su http://localhost:9090.

Opzione B — locale con PostgreSQL dockerizzato

# 1. Avvia solo PostgreSQL
docker compose up -d postgres

# 2. Avvia l'app in modalità dev (logging SQL + livello DEBUG sull'app)
./mvnw spring-boot:run

# 3. Smoke test
curl -s -X POST http://localhost:8080/api/v1/projects \
  -H 'content-type: application/json' \
  -d '{"name":"Demo","description":"Hello world"}' | jq

Requisiti minimi: JDK 21+, Docker, Maven (o ./mvnw).

---

🔌 API overview

Metodo	Path	Descrizione
POST	/api/v1/projects	Crea un progetto
GET	/api/v1/projects	Lista paginata (filtri: status)
GET	/api/v1/projects/{id}	Dettaglio
PUT	/api/v1/projects/{id}	Aggiorna nome/descrizione
POST	/api/v1/projects/{id}/archive	Archivia
POST	/api/v1/projects/{id}/reactivate	Riattiva
DELETE	/api/v1/projects/{id}	Elimina (cascade sui task)
POST	/api/v1/projects/{id}/tasks	Crea un task in un progetto
GET	/api/v1/projects/{id}/tasks	Lista task (filtri: status, priority)
GET	/api/v1/tasks/{id}	Dettaglio task
PUT	/api/v1/tasks/{id}	Aggiorna campi (escluso lo stato)
PATCH	/api/v1/tasks/{id}/status	Transizione di stato controllata
DELETE	/api/v1/tasks/{id}	Elimina un task

Documentazione completa generata: http://localhost:8080/v3/api-docs · UI: /swagger-ui.html.

---

📂 Struttura del repository

Spring-Boot-From-Scratch/
├── .github/
│   ├── workflows/         # CI, Docs (Pages), Release, CodeQL
│   ├── ISSUE_TEMPLATE/
│   └── dependabot.yml
├── docs/                  # MkDocs Material
│   ├── adr/               # Architecture Decision Records
│   ├── c4/                # Diagrammi C4 (Structurizr)
│   ├── steps/             # Guida didattica
│   └── api/               # API reference
├── ops/
│   └── prometheus.yml
├── src/
│   ├── main/
│   │   ├── java/dev/federicocalo/sbfs/
│   │   │   ├── project/   # Progetti: entity, repo, service, controller, dto
│   │   │   ├── task/      # Task: entity, repo, service, controller, dto, state
│   │   │   ├── common/    # Exception handling RFC 7807
│   │   │   └── config/    # OpenAPI config
│   │   └── resources/
│   │       ├── application*.yml
│   │       └── db/migration/V1__init.sql
│   └── test/
│       └── java/...       # Unit + Integration (Testcontainers)
├── compose.yaml           # PostgreSQL + Prometheus + app
├── Dockerfile             # Multi-stage layered JAR
├── mkdocs.yml
├── pom.xml
└── README.md

---

🧪 Testing

# Tutto il ciclo: compile, test unit, test integration (Testcontainers), coverage gate
./mvnw verify

# Solo unit test (più veloce, niente Docker)
./mvnw test -Dtest='!*IT'

# Report JaCoCo
open target/site/jacoco/index.html

• Unit test: state machine, entità di dominio, service con mock.
• Integration test: PostgreSQL reale via Testcontainers, MockMvc su tutti gli endpoint, error cases (404, 400, 409).
• Coverage gate: 70% di copertura linea (configurabile in pom.xml).

---

📚 Documentazione

Documentazione completa su GitHub Pages (deploy automatico via Actions):

🔗 https://fedcal.github.io/Spring-Boot-From-Scratch/

Contiene:

• Guida step-by-step — costruzione progressiva dell'applicazione, capitolo per capitolo.
• ADR — Architecture Decision Records (Clean Architecture, RFC 7807, Testcontainers vs H2…).
• Diagrammi C4 — context + container (Structurizr DSL).
• API reference — generata da OpenAPI 3.1.
• Troubleshooting e glossario.

---

🤝 Contribuire

Vedi CONTRIBUTING.md per workflow, convenzioni di commit (Conventional Commits) e checklist PR. Per vulnerabilità di sicurezza vedi SECURITY.md.

---

📄 Licenza

Distribuito sotto licenza MIT. Vedi LICENSE per il testo completo.

---

Built by Federico Calò — Full-Stack AI Engineer per startup e PMI IT/EU

🌐 federicocalo.dev