How josamvkd/global-exception-handling works
Project type & purpose (what you’re diagramming)
This repo is a single-service Spring Boot 4 REST API (Java 21, Maven) that demonstrates global exception handling for a simple Product CRUD domain using Spring Web + Spring Data JPA + Bean Validation and an in-memory H2 database (README mentions MySQL, but run instructions show H2 console and an H2 JDBC URL).
So the “system” is primarily:
• One HTTP API service
• One relational database (H2 in dev/demo; optionally MySQL)
• A clear internal layering: Controller → Service → Repository → DB
• A cross-cutting concern: GlobalExceptionHandler (@RestControllerAdvice) + validation pipeline producing a unified ApiErrorResponse
From src/main/java/com/josamtechie/api/...:
Runtime entry points / configuration
• GlobalExceptionHandlingApplication.java — Spring Boot application entrypoint (component scan / auto-config).
• application.properties — environment configuration (DB URL, JPA settings, etc.).
• DataInitializer.java — seeds sample data at startup (important “startup-time flow”).
Web/API layer
• controller/ProductController.java — REST endpoints: /api/products CRUD.
Business layer
• service/ProductService.java — business logic and deliberate exception throws.
• This is where BusinessException, DuplicateResourceException, ResourceNotFoundException originate.
Persistence layer
• repository/ProductRepository.java — Spring Data JPA repository.
• model/Product.java — JPA entity + Bean Validation annotations.
DTO and error model
• dto/ProductRequest.java — request payload (Java Record) with validation.
• dto/ApiErrorResponse.java — unified error payload (record, nested record for field errors).
Exception handling (cross-cutting)
• exception/GlobalExceptionHandler.java — the core of the demo: maps exceptions to HTTP responses.
• exception/*Exception.java — domain/business exceptions.
Tests
• GlobalExceptionHandlingApplicationTests.java — indicates at least a Spring Boot test context (optionally include in a “Dev/Test” view, not the runtime system view).
Normal request path (success)
Client → ProductController → ProductService → ProductRepository → DB
Then response returns back up the chain.
Error/exception path (the point of this repo)
Exceptions can arise from:
• Controller binding/validation: MethodArgumentNotValidException, HttpMessageNotReadableException, MethodArgumentTypeMismatchException
• Service/domain: ResourceNotFoundException, DuplicateResourceException, BusinessException
• Framework routing: NoResourceFoundException, HttpRequestMethodNotSupportedException
• Catch-all: Exception
All of these are intercepted by:
• GlobalExceptionHandler (@RestControllerAdvice) → returns ApiErrorResponse with correct HTTP status.
Database (H2 in-memory for demo; optionally MySQL as alternative)
4. (Optional) H2 Console as a browser-accessible tool hitting the DB (only in dev profile)
• Client → API Service: HTTP/JSON (/api/products)
• API Service → DB: JDBC via JPA/Hibernate
• (Optional) Browser → H2 Console: HTTP
• H2 Console → DB: JDBC/internal connection
Why this matters: it matches how the app is actually run (./mvnw spring-boot:run) and used (HTTP calls + DB).
Goal: show the internal architecture and exception flow.
Break the “API Service” container into components:
Web Layer
• ProductController
Validation & Binding (pipeline)
• Bean Validation (@Valid) on ProductRequest
• Message conversion (JSON → record) (source of HttpMessageNotReadableException)
• Path variable binding (source of MethodArgumentTypeMismatchException)
Business Layer
• ProductService
Persistence Layer
• ProductRepository (Spring Data JPA)
• Product entity
• JPA provider (Hibernate) (optional but helpful label)
Exception Handling (cross-cutting)
• GlobalExceptionHandler producing ApiErrorResponse
• Custom exceptions: ResourceNotFoundException, DuplicateResourceException, BusinessException
Startup/Data Seeding
• DataInitializer → ProductRepository (or service, depending on implementation) → DB
• Client → Controller: POST/GET/PUT/DELETE /api/products
• Controller → Service: method calls (createProduct, getProductById, etc.)
• Service → Repository: CRUD operations
• Repository → DB: persistence operations
• Service → throws → (caught by) GlobalExceptionHandler
• Controller/binding/validation → throws → GlobalExceptionHandler
• Framework routing/method mismatch → GlobalExceptionHandler
• GlobalExceptionHandler → Client: ApiErrorResponse (status, error, message, path, timestamp, fieldErrors[])
This repo’s “money shot”: make it visually obvious that *many exception sources funnel into one handler* that standardizes responses.
Request lifecycle (failure)
Same path, but at any stage an exception is thrown and intercepted by:
• GlobalExceptionHandler → builds ApiErrorResponse → returns correct HTTP status
Data initialization lifecycle
On startup:
• Spring Boot starts → DataInitializer runs → inserts products via repository/service → DB contains sample records.
Architectural patterns/design principles evident here (call them out
• Layered architecture: Controller (presentation) → Service (domain/business) → Repository (data access)
• DTO boundary: ProductRequest separates API contract from persistence entity Product
• Centralized error handling: @RestControllerAdvice produces a single error schema (ApiErrorResponse)
• Explicit domain exceptions: makes business rules readable and testable (BusinessException, etc.)
At minimum label:
• Spring Boot 4
• Spring Web / Spring MVC
• Spring Data JPA
• Bean Validation (Jakarta Validation)
• H2 (demo) / MySQL (optional target)
• Maven (build/run)
• Hibernate as JPA provider
Container View (Client ↔ Spring Boot Service ↔ DB)
2. Component View of Spring Boot Service (Controller/Service/Repository + Validation + GlobalExceptionHandler + DTOs)