java-spring-best-practices

Java Spring Boot Best Practices v2.0

Production-ready Spring Boot guide. Updated for Spring Boot 3.5.x / 4.0.x, Java 17+ (optimized for 21+).

What's New in v2.0

• Java Records as DTOs (immutable by default)
• Virtual Threads for high-concurrency I/O (spring.threads.virtual.enabled=true)
• ProblemDetail (RFC 7807) for standardized error responses
• RestClient replaces RestTemplate (fluent, synchronous)
• Structured Logging built into Spring Boot 3.4+
• Testcontainers as primary integration testing strategy (replaces H2)
• Observability with Micrometer Observation API
• Docker Compose integration for dev environments
• Sealed classes for exception hierarchies
• GraalVM Native Image / CDS awareness

Quick Start Checklist

• ✅ Java 17+ (21+ for Virtual Threads)
• ✅ spring-boot-starter-parent for dependency management
• ✅ Constructor injection with @RequiredArgsConstructor
• ✅ Java Records for DTOs (not mutable @Data classes)
• ✅ Controllers = routing only; Services = business logic
• ✅ ProblemDetail (RFC 7807) + @RestControllerAdvice
• ✅ @Valid + Bean Validation on record components
• ✅ SLF4J {} placeholders + structured logging
• ✅ YAML profiles (dev/prod/test)
• ✅ Unit tests (Mockito) + Integration tests (Testcontainers)
• ✅ spring.threads.virtual.enabled=true

Core Architecture

controller/   → HTTP routing only (thin)
    ↓
service/      → Business logic, caching, validation
    ↓
repository/   → Spring Data JPA
    ↓
entity/       → JPA domain models

Each layer depends only on layers below. Controllers never access repositories directly. See architecture.md for layer-based vs feature-based patterns.

Dependency Injection (Constructor Only)

@Service
@RequiredArgsConstructor
public class ProductService {
    private final ProductRepository repository;
    private final ProductMapper mapper;
}

Java Records as DTOs

Records replace @Data Lombok classes: immutable, concise, thread-safe.