The Ultimate Detailed Spring Boot Cheatsheet

// Spring Boot 3.4.x with Gradle (Kotlin DSL)
plugins {
    java
    id("org.springframework.boot") version "3.4.1"
    id("io.spring.dependency-management") version "1.1.7"
}

group = "com.example"
version = "1.0.0"
java.sourceCompatibility = JavaVersion.VERSION_21

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
    implementation("org.springframework.boot:spring-boot-starter-validation")
    implementation("org.springframework.boot:spring-boot-starter-actuator")
    runtimeOnly("com.h2database:h2")              // Dev DB
    runtimeOnly("org.postgresql:postgresql")       // Prod DB
    annotationProcessor("org.projectlombok:lombok")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testImplementation("org.testcontainers:junit-jupiter")
}

spring:
  application:
    name: my-app
  profiles:
    active: ${SPRING_PROFILES_ACTIVE:dev}

  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    driver-class-name: org.postgresql.Driver
    hikari:
      maximum-pool-size: 10
      minimum-idle: 5
      connection-timeout: 30000

  jpa:
    hibernate:
      ddl-auto: validate
    open-in-view: false
    properties:
      hibernate:
        format_sql: true
        default_batch_fetch_size: 100

  jackson:
    default-property-inclusion: non_null
    serialization:
      write-dates-as-timestamps: false

server:
  port: 8080
  tomcat:
    threads:
      max: 200
      min-spare: 10

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      show-details: when_authorized

logging:
  level:
    root: info
    com.example: debug
  structured:
    format:
      enabled: true

// ── Stereotype Annotations ──
@Component    // Generic Spring-managed bean
@Service      // Business logic layer (extends @Component)
@Repository   // Data access layer (auto-translates exceptions)
@Controller   // Web controller (returns view name)
@RestController // = @Controller + @ResponseBody (returns JSON)

// ── Constructor Injection (PREFERRED) ──
@Service
public class OrderService {
    private final OrderRepository orderRepo;
    private final PaymentService paymentService;
    private final AppProperties props;

    // Single constructor → @Autowired is optional
    public OrderService(OrderRepository orderRepo,
                        PaymentService paymentService,
                        AppProperties props) {
        this.orderRepo = orderRepo;
        this.paymentService = paymentService;
        this.props = props;
    }
}

// ── @Bean Configuration ──
@Configuration
public class AppConfig {

    @Bean
    @Primary
    public RestClient restClient(RestClient.Builder builder) {
        return builder.baseUrl("https://api.example.com")
            .defaultHeader("Accept", "application/json")
            .build();
    }

    @Bean
    @Profile("dev")
    public DataSource devDataSource() { /* H2 in-memory */ }

    @Bean
    @Scope(value = ConfigurableBeanFactory.SCOPE_PROTOTYPE)
    public PrototypeBean prototypeBean() { return new PrototypeBean(); }
}

@RestController
@RequestMapping("/api/v1/products")
@Validated
public class ProductController {

    private final ProductService service;

    public ProductController(ProductService service) {
        this.service = service;
    }

    @GetMapping
    public Page<ProductDto> list(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size,
            @RequestParam(required = false) String category) {
        return service.findAll(category, PageRequest.of(page, size));
    }

    @GetMapping("/{id}")
    public ProductDto get(@PathVariable UUID id) {
        return service.findById(id)
            .orElseThrow(() -> new NotFoundException("Product not found"));
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public ProductDto create(@Valid @RequestBody CreateProductRequest req) {
        return service.create(req);
    }

    @PutMapping("/{id}")
    public ProductDto update(@PathVariable UUID id,
                             @Valid @RequestBody UpdateProductRequest req) {
        return service.update(id, req);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable UUID id) {
        service.delete(id);
    }

    @GetMapping("/search")
    public List<ProductDto> search(
            @RequestParam String q,
            @RequestHeader(value = "X-Correlation-ID", required = false) String traceId) {
        return service.search(q);
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(NotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ErrorResponse handleNotFound(NotFoundException ex) {
        return new ErrorResponse(HttpStatus.NOT_FOUND.value(),
            ex.getMessage(), Instant.now());
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorResponse handleValidation(MethodArgumentNotValidException ex) {
        List<String> errors = ex.getBindingResult().getFieldErrors().stream()
            .map(f -> f.getField() + ": " + f.getDefaultMessage())
            .toList();
        return new ErrorResponse(400, "Validation failed", Instant.now(), errors);
    }

    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ErrorResponse handleGeneral(Exception ex) {
        return new ErrorResponse(500, "Internal server error", Instant.now());
    }
}

public record ErrorResponse(int status, String message,
        Instant timestamp, List<String> details) {
    public ErrorResponse(int s, String m, Instant t) { this(s, m, t, List.of()); }
}

@Entity
@Table(name = "users", uniqueConstraints = {
    @UniqueConstraint(columnNames = "email")
})
@EntityListeners(AuditingEntityListener.class)
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    private UUID id;

    @Column(nullable = false, length = 100)
    private String name;

    @Column(nullable = false, unique = true)
    private String email;

    @Enumerated(EnumType.STRING)
    private UserRole role;

    @OneToMany(mappedBy = "user", cascade = CascadeType.ALL,
               orphanRemoval = true, fetch = FetchType.LAZY)
    private List<Order> orders = new ArrayList<>();

    @CreatedDate @Column(updatable = false)
    private Instant createdAt;

    @LastModifiedDate
    private Instant updatedAt;

    // Getters/setters or use records (requires @ConstructorProperties)
}

// ── Repository ──
public interface UserRepository extends
        JpaRepository<User, UUID>,
        JpaSpecificationExecutor<User>,
        CustomUserRepository {

    Optional<User> findByEmail(String email);

    @Query("SELECT u FROM User u WHERE u.role = :role AND u.createdAt > :since")
    List<User> findByRoleAndCreatedAfter(@Param("role") UserRole role,
                                          @Param("since") Instant since);

    @Query(value = "SELECT * FROM users WHERE email LIKE %:keyword%",
           nativeQuery = true)
    List<User> searchNative(@Param("keyword") String keyword);

    boolean existsByEmail(String email);

    @Modifying
    @Query("DELETE FROM User u WHERE u.lastLogin < :cutoff")
    int deleteInactiveUsers(@Param("cutoff") Instant cutoff);
}

// ── Dynamic queries with Specification API ──
public class UserSpecs {
    public static Specification<User> hasRole(UserRole role) {
        return (root, query, cb) -> cb.equal(root.get("role"), role);
    }
    public static Specification<User> nameContains(String name) {
        return (root, query, cb) ->
            cb.like(cb.lower(root.get("name")), "%" + name.toLowerCase() + "%");
    }
    public static Specification<User> createdAfter(Instant date) {
        return (root, query, cb) -> cb.greaterThan(root.get("createdAt"), date);
    }
}

// Usage:
Specification<User> spec = Specification
    .where(UserSpecs.hasRole(UserRole.ADMIN))
    .and(UserSpecs.nameContains("John"));
Page<User> result = userRepository.findAll(spec, PageRequest.of(0, 20));

@Configuration
@EnableWebSecurity
@EnableMethodSecurity  // enables @PreAuthorize, @Secured, @RolesAllowed
public class SecurityConfig {

    private final JwtAuthenticationFilter jwtFilter;
    private final UserDetailsService userDetailsService;

    // ── SecurityFilterChain (new style — no WebSecurityConfigurerAdapter) ──
    @Bean
    @Order(1)
    public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
        return http
            .securityMatcher("/api/**")
            .csrf(csrf -> csrf.disable())
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/v1/auth/**").permitAll()
                .requestMatchers("/api/v1/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .authenticationProvider(authenticationProvider())
            .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class)
            .exceptionHandling(ex -> ex
                .authenticationEntryPoint(new JwtAuthenticationEntryPoint())
            )
            .headers(h -> h.contentSecurityPolicy(csp -> csp.policyDirectives("default-src 'self'")))
            .build();
    }

    @Bean
    @Order(2)
    public SecurityFilterChain formFilterChain(HttpSecurity http) throws Exception {
        return http
            .formLogin(form -> form.loginPage("/login").permitAll())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/", "/home", "/register").permitAll()
                .anyRequest().authenticated()
            )
            .build();
    }

    @Bean
    public AuthenticationProvider authenticationProvider() {
        DaoAuthenticationProvider provider = new DaoAuthenticationProvider();
        provider.setUserDetailsService(userDetailsService);
        provider.setPasswordEncoder(passwordEncoder());
        return provider;
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(12);  // strength 4-31
    }
}

@WebMvcTest(ProductController.class)
class ProductControllerTest {

    @Autowired private MockMvc mockMvc;
    @Autowired private ObjectMapper objectMapper;
    @MockBean private ProductService productService;

    @Test
    void shouldReturnProductById() throws Exception {
        ProductDto dto = new ProductDto(UUID.randomUUID(),
            "Widget", BigDecimal.valueOf(29.99), "ELECTRONICS");

        when(productService.findById(any())).thenReturn(Optional.of(dto));

        mockMvc.perform(get("/api/v1/products/{id}", dto.id()))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value("Widget"))
            .andExpect(jsonPath("$.price").value(29.99));
    }

    @Test
    void shouldCreateProduct() throws Exception {
        CreateProductRequest req = new CreateProductRequest(
            "Widget", BigDecimal.valueOf(29.99), "ELECTRONICS");
        ProductDto dto = new ProductDto(UUID.randomUUID(),
            "Widget", BigDecimal.valueOf(29.99), "ELECTRONICS");

        when(productService.create(any())).thenReturn(dto);

        mockMvc.perform(post("/api/v1/products")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(req)))
            .andExpect(status().isCreated())
            .andExpect(jsonPath("$.id").exists());
    }

    @Test
    void shouldReturn404WhenNotFound() throws Exception {
        when(productService.findById(any())).thenReturn(Optional.empty());

        mockMvc.perform(get("/api/v1/products/{id}", UUID.randomUUID()))
            .andExpect(status().isNotFound());
    }
}

@RestController
@RequestMapping("/api/v2/products")
public class ReactiveProductController {

    private final ReactiveProductRepository repo;

    public ReactiveProductController(ReactiveProductRepository repo) {
        this.repo = repo;
    }

    @GetMapping("/{id}")
    public Mono<ProductDto> getById(@PathVariable String id) {
        return repo.findById(id)
            .map(this::toDto)
            .switchIfEmpty(Mono.error(new NotFoundException("Not found")));
    }

    @GetMapping
    public Flux<ProductDto> list() {
        return repo.findAll().map(this::toDto);
    }

    @GetMapping("/stream")
    public Flux<ServerSentEvent<ProductDto>> streamProducts() {
        return repo.findAll()
            .map(dto -> ServerSentEvent.<ProductDto>builder()
                .data(dto)
                .event("product-update")
                .build());
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Mono<ProductDto> create(@Valid @RequestBody CreateProductRequest req) {
        return repo.save(toEntity(req)).map(this::toDto);
    }
}

@Configuration
public class ResilienceConfig {

    @Bean
    public CircuitBreaker circuitBreaker(
            CircuitBreakerRegistry registry) {
        CircuitBreakerConfig config = CircuitBreakerConfig.custom()
            .failureRateThreshold(50)             // open at 50% failure
            .waitDurationInOpenState(Duration.ofSeconds(30))
            .slidingWindowSize(10)                // last 10 calls
            .permittedNumberOfCallsInHalfOpenState(3)
            .build();
        return registry.circuitBreaker("default", config);
    }

    @Bean
    public Retry retry(RetryRegistry registry) {
        RetryConfig config = RetryConfig.custom()
            .maxAttempts(3)
            .waitDuration(Duration.ofMillis(500))
            .retryOnException(e -> e instanceof WebClientResponseException
                && ((WebClientResponseException) e)
                    .getStatusCode().is5xxServerError())
            .build();
        return registry.retry("default", config);
    }
}

@Configuration
@EnableBatchProcessing
public class UserImportBatchConfig {

    @Bean
    public Job importUserJob(JobRepository jobRepo,
                              Step importStep,
                              JobListener listener) {
        return new JobBuilder("importUsers", jobRepo)
            .listener(listener)
            .start(importStep)
            .build();
    }

    @Bean
    public Step importStep(JobRepository jobRepo,
                           PlatformTransactionManager txMgr,
                           ItemReader<UserRecord> reader,
                           ItemProcessor<UserRecord, User> processor,
                           ItemWriter<User> writer) {
        return new StepBuilder("importUsersStep", jobRepo)
            .<UserRecord, User>chunk(500, txMgr)
            .reader(reader)
            .processor(processor)
            .writer(writer)
            .faultTolerant()
            .skipLimit(50)
            .skip(ValidationException.class)
            .listener(skipListener())
            .build();
    }

    @Bean
    public FlatFileItemReader<UserRecord> flatReader() {
        return new FlatFileItemReaderBuilder<UserRecord>()
            .name("userReader")
            .resource(new ClassPathResource("users.csv"))
            .delimited().delimiter(",")
            .names("name", "email", "role")
            .fieldSetMapper(fs -> new UserRecord(
                fs.readString("name"), fs.readString("email"),
                UserRole.valueOf(fs.readString("role"))))
            .build();
    }
}

@Configuration
public class SpringAiConfig {

    @Bean
    public ChatClient chatClient(ChatModel chatModel) {
        return ChatClient.builder(chatModel)
            .defaultSystem("""
                You are a helpful customer support assistant
                for an e-commerce platform. Be concise and friendly.
                Today's date: ${java.time.LocalDate.now()}
                """)
            .defaultAdvisors(new MessageChatMemoryAdvisor(
                new InMemoryChatMemory()))
            .build();
    }
}

@RestController
@RequestMapping("/api/v1/ai")
public class AiController {

    private final ChatClient chatClient;
    private final VectorStore vectorStore;
    private final EmbeddingModel embeddingModel;

    // ── Simple Chat ──
    @GetMapping("/chat")
    public String chat(@RequestParam String message) {
        return chatClient.prompt()
            .user(message)
            .call()
            .content();
    }

    // ── Structured Output (returns Java object) ──
    @GetMapping("/analyze")
    public SentimentResult analyze(@RequestParam String text) {
        return chatClient.prompt()
            .user("Analyze sentiment: " + text)
            .call()
            .entity(SentimentResult.class);  // Auto-parsed
    }

    // ── Tool Calling / Function Calling ──
    @GetMapping("/order-status")
    public String orderStatus(@RequestParam String orderId) {
        return chatClient.prompt()
            .user("What is the status of order " + orderId + "?")
            .functions("getOrderStatus")  // registered tool
            .call()
            .content();
    }
}

// ── Tool Registration ──
@Bean
@Description("Get the current status of an order by ID")
public Function<OrderStatusRequest, OrderStatusResponse> getOrderStatus() {
    return request -> orderService
        .getStatus(UUID.fromString(request.orderId()));
}

@Configuration
@EnableCaching
public class CachingConfig {

    @Bean
    public CacheManager cacheManager() {
        CaffeineCacheManager manager = new CaffeineCacheManager();
        manager.setCacheSpecification(
            "expireAfterWrite=10m, maximumSize=1000");
        manager.setCacheNames(List.of(
            "users", "products", "categories"));
        return manager;
    }
}

// ── Usage in Service Layer ──
@Service
public class ProductService {

    @Cacheable(value = "products", key = "#id",
               unless = "#result == null")
    public ProductDto findById(UUID id) {
        return productMapper.toDto(repository.findById(id)
            .orElseThrow());
    }

    @CachePut(value = "products", key = "#result.id")
    public ProductDto update(UUID id, UpdateProductRequest req) {
        Product entity = repository.findById(id).orElseThrow();
        productMapper.update(req, entity);
        return productMapper.toDto(repository.save(entity));
    }

    @CacheEvict(value = "products", key = "#id")
    public void delete(UUID id) {
        repository.deleteById(id);
    }

    @Caching(evict = {
        @CacheEvict(value = "products", allEntries = true),
        @CacheEvict(value = "categories", key = "#req.category()")
    })
    public ProductDto create(CreateProductRequest req) { /*...*/ }
}

// ── Virtual Threads (Java 21+, enabled by default in Boot 3.4+) ──
// application.yml
// spring.threads.virtual.enabled: true

// ── RestClient (Spring Boot 3.4+) ──
@Configuration
public class RestClientConfig {

    @Bean
    public RestClient restClient(RestClient.Builder builder) {
        return builder
            .baseUrl("https://api.example.com")
            .defaultHeader("Authorization", "Bearer {token}")
            .requestFactory(new JdkClientHttpRequestFactory())  // uses virtual threads
            .build();
    }

    @Bean
    @Primary
    public RestClient.Builder restClientBuilder() {
        return RestClient.builder();
    }
}

// ── CRaC (Coordinated Restore at Checkpoint) ──
// Enables snapshotting running JVM state for instant startup
// Add: org.crac:crac dependency
// Build: -XX:CRaCCheckpointTo=checkpoint.jfr
// Restore: -XX:CRaCRestoreFrom=checkpoint.jfr

-- ── Flyway Versioned Migrations ──
-- Location: src/main/resources/db/migration/
-- Naming: V{version}__{description}.sql

-- V1__create_users_table.sql
CREATE TABLE users (
    id      UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name    VARCHAR(100) NOT NULL,
    email   VARCHAR(255) NOT NULL UNIQUE,
    role    VARCHAR(30)  NOT NULL DEFAULT 'USER',
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- V2__add_users_indexes.sql
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_role  ON users(role);

-- V3__add_audit_columns.sql
ALTER TABLE users ADD COLUMN last_login TIMESTAMPTZ;

-- R__refresh_materialized_view.sql  (Repeatable: runs if checksum changes)
REFRESH MATERIALIZED VIEW CONCURRENTLY analytics_view;

-- U3__undo_add_audit_columns.sql  (Undo: flyway undo (requires Pro license))
-- ALTER TABLE users DROP COLUMN last_login;