Spring Boot REST: JPA, Validation, Exception Handling, and Testing

controller/ → service/ → repository/ → entity/ → database/

@Entity
@Table(name = "products", indexes = {
    @Index(name = "idx_product_sku", columnList = "sku", unique = true),
    @Index(name = "idx_product_category", columnList = "category")
})
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
 
    @Version
    private Long version;
 
    @Column(nullable = false, length = 200)
    private String name;
 
    @Column(nullable = false, unique = true, length = 50)
    private String sku;
 
    @Column(nullable = false, precision = 10, scale = 2)
    private BigDecimal price;
 
    @Column(nullable = false)
    private Integer stockQuantity;
 
    @Column(nullable = false, length = 100)
    private String category;
 
    @Column(nullable = false)
    private Boolean active = true;
 
    @CreationTimestamp
    @Column(nullable = false, updatable = false)
    private Instant createdAt;
 
    @UpdateTimestamp
    @Column(nullable = false)
    private Instant updatedAt;
    // Getters, setters, constructors…
}

public interface ProductRepository extends JpaRepository<Product, Long> {
    Optional<Product> findBySku(String sku);
    Page<Product> findByActiveTrue(Pageable pageable);
 
    @Query("SELECT p FROM Product p WHERE p.price BETWEEN :min AND :max AND p.active = true")
    List<Product> findByPriceRange(@Param("min") BigDecimal min, @Param("max") BigDecimal max);
 
    @Modifying
    @Query("UPDATE Product p SET p.active = false WHERE p.stockQuantity = 0")
    int deactivateOutOfStockProducts();
}

public record CreateProductRequest(
    @NotBlank @Size(min = 2, max = 200) String name,
    @NotBlank @Pattern(regexp = "^[A-Z]{2,4}-\\d{4,8}$") String sku,
    @NotNull @DecimalMin("0.01") @DecimalMax("999999.99") BigDecimal price,
    @NotNull @Min(0) Integer stockQuantity,
    @NotBlank String category
) {}
 
public record ProductResponse(
    Long id, String name, String sku, BigDecimal price,
    Integer stockQuantity, String category, Boolean active,
    Long version, Instant createdAt, Instant updatedAt
) {
    public static ProductResponse from(Product entity) {
        return new ProductResponse(entity.getId(), entity.getName(), entity.getSku(),
            entity.getPrice(), entity.getStockQuantity(), entity.getCategory(),
            entity.getActive(), entity.getVersion(), entity.getCreatedAt(), entity.getUpdatedAt());
    }
}

@RestController
@RequestMapping("/api/v1/products")
public class ProductController {
    private final ProductService productService;
 
    @GetMapping("/{id}")
    public ResponseEntity<ProductResponse> getProduct(
            @PathVariable Long id,
            HttpServletRequest request) {
        ProductResponse product = productService.findById(id);
        String etag = "\"" + product.version() + "\"";
        if (request.checkNotModified(etag)) {
            return null; // Spring returns 304 Not Modified
        }
        return ResponseEntity.ok().eTag(etag).body(product);
    }
 
    @PostMapping
    public ResponseEntity<ProductResponse> createProduct(
            @Valid @RequestBody CreateProductRequest request) {
        ProductResponse created = productService.create(request);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
                .path("/{id}").buildAndExpand(created.id()).toUri();
        String etag = "\"" + created.version() + "\"";
        return ResponseEntity.created(location).eTag(etag).body(created);
    }
 
    @PutMapping("/{id}")
    public ResponseEntity<ProductResponse> updateProduct(
            @PathVariable Long id,
            @Valid @RequestBody UpdateProductRequest request,
            @RequestHeader(value = "If-Match", required = false) String ifMatch) {
        Long version = parseVersion(ifMatch);
        ProductResponse updated = productService.update(id, request, version);
        return ResponseEntity.ok().eTag("\"" + updated.version() + "\"").body(updated);
    }
 
    @PatchMapping(value = "/{id}", consumes = "application/merge-patch+json")
    public ResponseEntity<ProductResponse> patchProduct(
            @PathVariable Long id,
            @RequestBody PatchProductRequest request,
            @RequestHeader(value = "If-Match", required = false) String ifMatch) {
        Long version = parseVersion(ifMatch);
        ProductResponse patched = productService.patch(id, request, version);
        return ResponseEntity.ok().eTag("\"" + patched.version() + "\"").body(patched);
    }
 
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteProduct(@PathVariable Long id) {
        productService.delete(id);
        return ResponseEntity.noContent().build();
    }
 
    private Long parseVersion(String ifMatch) {
        if (ifMatch == null || ifMatch.isBlank()) return null;
        String raw = ifMatch.replaceAll("(W/)?\"", "");
        return Long.parseLong(raw);
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ProblemDetail> handleValidationError(MethodArgumentNotValidException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "Validation failed");
        problem.setTitle("Validation Error");
        problem.setProperty("errors", ex.getBindingResult().getFieldErrors()
            .stream().collect(Collectors.toMap(FieldError::getField, FieldError::getDefaultMessage)));
        return ResponseEntity.badRequest().body(problem);
    }
 
    @ExceptionHandler(OptimisticLockingFailureException.class)
    public ResponseEntity<ProblemDetail> handleConcurrency(OptimisticLockingFailureException ex) {
        return ResponseEntity.status(HttpStatus.CONFLICT)
            .body(ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, "Resource was modified"));
    }
}

@DataJpaTest
class ProductRepositoryTest {
    @Autowired private ProductRepository repo;
 
    @Test
    void findBySku_returnsProduct() {
        Product p = new Product();
        p.setName("Test");
        p.setSku("TP-1234");
        p.setPrice(new BigDecimal("10.00"));
        repo.save(p);
        
        assertThat(repo.findBySku("TP-1234")).isPresent()
            .get().extracting(Product::getName).isEqualTo("Test");
    }
}
 
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@Testcontainers
class ProductIntegrationTest {
    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");
 
    @Autowired private TestRestTemplate restTemplate;
 
    @Test
    void fullCrudLifecycle() {
        var createRequest = Map.of("name", "Widget", "sku", "WG-5678", "price", 49.99, "stockQuantity", 200, "category", "Testing");
        ResponseEntity<ProductResponse> response = restTemplate.postForEntity("/api/v1/products", createRequest, ProductResponse.class);
        
        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
        assertThat(response.getHeaders().getLocation()).isNotNull();
    }
}

# application.yml — production HikariCP + JPA defaults
spring:
  datasource:
    hikari:
      # Pool size: leave headroom on Postgres. With 5 replicas of this service
      # and Postgres max_connections=200, 20 per pod = 100 total, 50% headroom.
      maximum-pool-size: 20
      minimum-idle: 5
 
      # Timeout chain: each one fails faster than the next layer up.
      # connection-timeout: how long an app thread waits for a free connection
      connection-timeout: 3000              # 3s — never block a request for longer
      validation-timeout: 1000              # 1s — connection-test query budget
      idle-timeout: 600000                  # 10min
      max-lifetime: 1800000                 # 30min — must be < Postgres idle_in_transaction_timeout
      keepalive-time: 60000                 # 1min — beats most NAT/firewall idle drops
 
      # Leak detection: log a warning if a connection is held > 30s.
      # Always-on in staging; disable in prod only if false-positive noise is unbearable.
      leak-detection-threshold: 30000
 
  jpa:
    properties:
      hibernate:
        # Statement-level timeout — every query inherits this unless overridden.
        # Tighter than HTTP request timeout (typically 5s) so DB doesn't hold the budget.
        jdbc.timeout: 2000
        # Disable open-session-in-view: forces explicit fetch decisions in service layer
        # instead of N+1 queries materialising silently in the controller.
        enable_lazy_load_no_trans: false
    open-in-view: false

// TransactionConfig.java — the timeout that defaults wrong
import org.springframework.context.annotation.Configuration;
import org.springframework.transaction.annotation.EnableTransactionManagement;
import org.springframework.transaction.annotation.TransactionManagementConfigurer;
import org.springframework.transaction.PlatformTransactionManager;
 
@Configuration
@EnableTransactionManagement
public class TransactionConfig implements TransactionManagementConfigurer {
 
    private final PlatformTransactionManager txManager;
 
    public TransactionConfig(PlatformTransactionManager txManager) {
        // Default timeout for every @Transactional that doesn't specify one.
        // Spring's default is "no timeout" — a hung query holds a connection
        // until the OS-level TCP keepalive triggers, often minutes.
        if (txManager instanceof org.springframework.orm.jpa.JpaTransactionManager jpa) {
            jpa.setDefaultTimeout(5);  // seconds
        }
        this.txManager = txManager;
    }
 
    @Override
    public PlatformTransactionManager annotationDrivenTransactionManager() {
        return txManager;
    }
}

@Configuration
public class WebClientConfig {
 
    @Bean
    public WebClient downstreamClient(
            ReactiveCircuitBreakerFactory<?, ?> cbFactory,
            @Value("${downstream.base-url}") String baseUrl) {
 
        // Reactor Netty HttpClient with explicit timeouts at every layer.
        // connect-timeout: TCP handshake budget. response-timeout: total round-trip.
        // ReadTimeoutHandler/WriteTimeoutHandler: per-byte stalls between TCP packets.
        HttpClient httpClient = HttpClient.create()
                .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 2_000)
                .responseTimeout(Duration.ofSeconds(3))
                .doOnConnected(conn -> conn
                        .addHandlerLast(new ReadTimeoutHandler(3, TimeUnit.SECONDS))
                        .addHandlerLast(new WriteTimeoutHandler(3, TimeUnit.SECONDS)));
 
        return WebClient.builder()
                .baseUrl(baseUrl)
                .clientConnector(new ReactorClientHttpConnector(httpClient))
                .filter((request, next) -> next.exchange(request)
                        // Bound retries to idempotent verbs only — POST replays double-bill customers.
                        .transformDeferred(mono -> isIdempotent(request)
                                ? mono.retryWhen(Retry.backoff(2, Duration.ofMillis(200))
                                        .maxBackoff(Duration.ofSeconds(2))
                                        .filter(WebClientConfig::isRetryable))
                                : mono))
                .build();
    }
 
    private static boolean isIdempotent(ClientRequest req) {
        HttpMethod m = req.method();
        return m == HttpMethod.GET || m == HttpMethod.HEAD
                || m == HttpMethod.PUT || m == HttpMethod.DELETE;
    }
 
    private static boolean isRetryable(Throwable t) {
        if (t instanceof WebClientResponseException ex) {
            int code = ex.getStatusCode().value();
            return code == 502 || code == 503 || code == 504;
        }
        return t instanceof IOException || t instanceof TimeoutException;
    }
}

@Service
public class InventoryClient {
    private final WebClient downstreamClient;
    private final ReactiveCircuitBreaker breaker;
 
    public InventoryClient(WebClient downstreamClient, ReactiveCircuitBreakerFactory<?, ?> cbFactory) {
        this.downstreamClient = downstreamClient;
        // Default config: 50% failure rate over 100 calls trips the breaker for 30s.
        // Tune slidingWindowType=TIME_BASED if traffic is bursty so a single 1-RPS minute
        // can't keep an unhealthy breaker closed.
        this.breaker = cbFactory.create("inventory");
    }
 
    public Mono<StockLevel> stockFor(String sku) {
        Mono<StockLevel> upstream = downstreamClient.get()
                .uri("/inventory/{sku}", sku)
                .retrieve()
                .onStatus(HttpStatusCode::is4xxClientError, resp ->
                        // 4xx is a contract bug — fail fast, do NOT trip the breaker
                        resp.createException().flatMap(Mono::error))
                .bodyToMono(StockLevel.class);
 
        return breaker.run(upstream, throwable -> {
            // Fallback path: serve the last cached value or a stock-aware default.
            // Returning Mono.error here would propagate, so callers see graceful degradation.
            return Mono.just(StockLevel.unknown(sku));
        });
    }
}

@Configuration
public class HibernateTuningConfig implements HibernatePropertiesCustomizer {
 
    @Override
    public void customize(Map<String, Object> props) {
        // Plan cache: bigger is fine — entries are small and parse cost is high.
        // Default is 2048; raise on services with many @Query variants or Criteria queries.
        props.put("hibernate.query.plan_cache_max_size", 4096);
        props.put("hibernate.query.plan_parameter_metadata_max_size", 256);
 
        // Statement caching at the JDBC level — separate from plan cache.
        // Reuses PreparedStatement objects so the JDBC driver doesn't re-prepare on Postgres.
        props.put("hibernate.jdbc.batch_size", 50);
        props.put("hibernate.order_inserts", true);
        props.put("hibernate.order_updates", true);
 
        // Statistics: log slow queries and expose JMX/Micrometer metrics.
        // Keep off in prod hot paths — there's a small per-query overhead — but turn on
        // in staging or behind a feature flag during incident triage.
        props.put("hibernate.generate_statistics", true);
        props.put("hibernate.session.events.log.LOG_QUERIES_SLOWER_THAN_MS", 50);
    }
}

@Component
public class DownstreamReadinessIndicator implements ReactiveHealthIndicator {
    private final InventoryClient inventoryClient;
 
    public DownstreamReadinessIndicator(InventoryClient inventoryClient) {
        this.inventoryClient = inventoryClient;
    }
 
    @Override
    public Mono<Health> health() {
        // Use a known-cheap probe SKU. Do NOT call /healthz on the downstream — it lies.
        // Probe the same code path real traffic uses so a misconfigured route is caught.
        return inventoryClient.stockFor("__probe__")
                .timeout(Duration.ofMillis(500))
                .map(stock -> Health.up().withDetail("sku", stock.sku()).build())
                .onErrorResume(ex -> Mono.just(Health.outOfService()
                        .withDetail("reason", ex.getClass().getSimpleName())
                        .build()));
    }
}

# application.yml — readiness composition + Micrometer wiring
management:
  endpoint:
    health:
      probes:
        enabled: true
      show-details: when-authorized
      group:
        readiness:
          # Order matters for the response payload but not for the aggregate status.
          # Liveness is intentionally narrower — only "is the JVM stuck?" trips a pod restart.
          include: db, diskSpace, downstreamReadiness
        liveness:
          include: livenessState
  endpoints:
    web:
      exposure:
        include: health, info, prometheus, metrics
  metrics:
    tags:
      application: ${spring.application.name}
      env: ${SPRING_PROFILES_ACTIVE:unknown}
    distribution:
      percentiles-histogram:
        http.server.requests: true
      slo:
        http.server.requests: 50ms, 100ms, 200ms, 500ms