Spring Boot Validation — 2GB Payload Crashes Without @Valid

package io.thecodeforge.dto;

import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotNull;
import lombok.Data;

/**
 * Standard DTO for user operations.
 * Uses Jakarta Bean Validation for declarative constraints.
 *
 * Note: age is declared as Integer (not int) intentionally.
 * @NotNull on a primitive int is meaningless — primitives default
 * to 0 and can never be null. Use the boxed type when nullability matters.
 */
@Data
public class UserDto {

    @NotBlank(message = "Username is required")
    @Size(min = 3, max = 20, message = "Username must be between {min} and {max} characters")
    private String username;

    @Email(message = "Invalid email format")
    @NotBlank(message = "Email cannot be empty")
    private String email;

    @NotNull(message = "Age is required")
    @Min(value = 18, message = "User must be at least {value} years old")
    private Integer age;
}

package io.thecodeforge.validation;

/**
 * Marker interfaces for validation groups.
 * No methods — these are type tokens used only as group identifiers.
 * Constraints with no group specified belong to Default.class
 * and are evaluated regardless of which group is active.
 */
public interface ValidationGroups {
    interface Create {}
    interface Update {}
}

// ---

package io.thecodeforge.dto;

import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Null;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Email;
import io.thecodeforge.validation.ValidationGroups;
import lombok.Data;

@Data
public class UserRequestDto {

    // Null during create (DB generates it), not-null during update.
    // Constraints with groups= are only evaluated when that group is active.
    @Null(groups = ValidationGroups.Create.class, message = "ID must be absent for creation")
    @NotNull(groups = ValidationGroups.Update.class, message = "ID is required for update")
    private Long id;

    // No groups= here: belongs to Default.class, always evaluated.
    @NotBlank(message = "Username is required")
    private String username;

    @NotBlank(message = "Email is required")
    @Email(message = "Invalid email format")
    private String email;
}

// ---

package io.thecodeforge.controller;

import io.thecodeforge.dto.UserRequestDto;
import io.thecodeforge.validation.ValidationGroups;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @PostMapping
    public UserRequestDto create(
            @Validated(ValidationGroups.Create.class) @RequestBody UserRequestDto dto) {
        // ID is validated as null.
        // username and email are validated (Default group always applies).
        return dto;
    }

    @PutMapping("/{id}")
    public UserRequestDto update(
            @PathVariable Long id,
            @Validated(ValidationGroups.Update.class) @RequestBody UserRequestDto dto) {
        // ID is validated as not-null.
        // username and email are validated (Default group always applies).
        return dto;
    }
}

package io.thecodeforge.exception;

import jakarta.validation.ConstraintViolation;
import jakarta.validation.ConstraintViolationException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;

import java.time.LocalDateTime;
import java.util.List;
import java.util.stream.Collectors;

/**
 * Global exception handler for all Spring MVC controllers.
 * Catches both @RequestBody validation failures and path/param validation failures.
 * Returns structured JSON — never exposes stack traces to API consumers.
 */
@RestControllerAdvice
public class GlobalExceptionHandler {

    /**
     * Handles @Valid / @Validated failures on @RequestBody parameters.
     * Thrown as MethodArgumentNotValidException by Spring MVC.
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleRequestBodyValidation(
            MethodArgumentNotValidException ex, WebRequest request) {

        List<FieldErrorDetail> fieldErrors = ex.getBindingResult()
                .getAllErrors()
                .stream()
                .map(error -> {
                    String field = ((FieldError) error).getField();
                    String message = error.getDefaultMessage();
                    return new FieldErrorDetail(field, message);
                })
                .collect(Collectors.toList());

        ErrorResponse body = new ErrorResponse(
                LocalDateTime.now(),
                HttpStatus.BAD_REQUEST.value(),
                "Validation failed",
                fieldErrors,
                request.getDescription(false).replace("uri=", "")
        );

        return ResponseEntity.badRequest().body(body);
    }

    /**
     * Handles validation failures on path variables and request parameters.
     * Thrown as ConstraintViolationException when @Validated is at class level.
     * Also handles service-layer @Validated method validation.
     */
    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<ErrorResponse> handleConstraintViolation(
            ConstraintViolationException ex, WebRequest request) {

        List<FieldErrorDetail> fieldErrors = ex.getConstraintViolations()
                .stream()
                .map(violation -> {
                    // Extract the last path node as the field name
                    String field = getFieldName(violation);
                    String message = violation.getMessage();
                    return new FieldErrorDetail(field, message);
                })
                .collect(Collectors.toList());

        ErrorResponse body = new ErrorResponse(
                LocalDateTime.now(),
                HttpStatus.BAD_REQUEST.value(),
                "Constraint violation",
                fieldErrors,
                request.getDescription(false).replace("uri=", "")
        );

        return ResponseEntity.badRequest().body(body);
    }

    private String getFieldName(ConstraintViolation<?> violation) {
        String path = violation.getPropertyPath().toString();
        // Path format: methodName.paramName — return only the param name
        int lastDot = path.lastIndexOf('.');
        return lastDot >= 0 ? path.substring(lastDot + 1) : path;
    }

    // Response types as Java records (Java 16+)
    public record ErrorResponse(
            LocalDateTime timestamp,
            int status,
            String message,
            List<FieldErrorDetail> errors,
            String path
    ) {}

    public record FieldErrorDetail(String field, String message) {}
}

package io.thecodeforge.validation;

import jakarta.validation.Constraint;
import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;
import jakarta.validation.Payload;
import io.thecodeforge.dto.RegistrationDto;

import java.lang.annotation.*;

// --- Annotation definition ---

@Documented
@Constraint(validatedBy = PasswordMatchValidator.class)
@Target(ElementType.TYPE)   // class-level — receives the entire DTO
@Retention(RetentionPolicy.RUNTIME)
public @interface PasswordMatch {
    String message() default "Passwords do not match";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

// --- Validator implementation ---

public class PasswordMatchValidator
        implements ConstraintValidator<PasswordMatch, RegistrationDto> {

    @Override
    public boolean isValid(RegistrationDto dto, ConstraintValidatorContext context) {
        if (dto.getPassword() == null || dto.getConfirmPassword() == null) {
            // Let @NotBlank handle nulls — do not duplicate that check here
            return true;
        }

        boolean matches = dto.getPassword().equals(dto.getConfirmPassword());

        if (!matches) {
            // Attach the error to confirmPassword field, not the class.
            // Without this, GlobalExceptionHandler may not surface the error
            // because it iterates FieldError objects, not class-level violations.
            context.disableDefaultConstraintViolation();
            context
                .buildConstraintViolationWithTemplate("Passwords do not match")
                .addPropertyNode("confirmPassword")
                .addConstraintViolation();
        }

        return matches;
    }
}

// --- DTO with cascaded and cross-field validation ---

package io.thecodeforge.dto;

import io.thecodeforge.validation.PasswordMatch;
import jakarta.validation.Valid;
import jakarta.validation.constraints.*;
import lombok.Data;
import java.util.List;

@PasswordMatch  // class-level: cross-field validator
@Data
public class RegistrationDto {

    @NotBlank(message = "Password is required")
    @Size(min = 8, message = "Password must be at least {min} characters")
    private String password;

    private String confirmPassword;

    // Cascaded validation: @Valid causes Bean Validation to recurse
    // into AddressDto and evaluate its constraints.
    // Without @Valid here, AddressDto annotations are never evaluated.
    @Valid
    @NotNull(message = "Address is required")
    private AddressDto address;

    // Cascaded validation also works on collections.
    // @Valid validates each OrderItemDto element in the list.
    @Valid
    @NotEmpty(message = "Order must contain at least one item")
    private List<OrderItemDto> items;
}

package io.thecodeforge.service;

import io.thecodeforge.dto.UserDto;
import jakarta.validation.Valid;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import org.springframework.stereotype.Service;
import org.springframework.validation.annotation.Validated;

/**
 * @Validated at the class level activates Spring AOP-based method validation.
 * Constraint annotations on method parameters are enforced via a proxy.
 * Throws ConstraintViolationException (not MethodArgumentNotValidException)
 * when a constraint is violated — ensure your GlobalExceptionHandler covers both.
 */
@Service
@Validated
public class UserService {

    /**
     * @Valid on the DTO parameter triggers full Bean Validation on the object.
     * Constraints on UserDto (username, email, age) are all evaluated.
     */
    public UserDto createUser(@Valid UserDto dto) {
        // By the time execution reaches here, dto is validated.
        // This guarantees validation regardless of which caller invokes this method.
        return dto;
    }

    /**
     * Constraint annotations directly on primitive parameters.
     * @Min(1) ensures id is a positive number — no DTO wrapper needed.
     */
    public UserDto findById(@Min(value = 1, message = "User ID must be positive") Long id) {
        // id is guaranteed to be >= 1
        return new UserDto();
    }

    /**
     * @NotBlank directly on a String parameter.
     */
    public void deleteByUsername(
            @NotBlank(message = "Username must not be blank") String username) {
        // username is guaranteed to be non-null and non-empty
    }
}

package io.thecodeforge.controller;

import io.thecodeforge.dto.UserDto;
import jakarta.validation.Valid;
import jakarta.validation.constraints.Min;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

// @Validated at class level activates path variable and request param validation.
// Without this, @Min on the path variable does nothing.
@Validated
@RestController
@RequestMapping("/api/users")
public class UserController {

    // CORRECT: @Valid triggers @RequestBody validation.
    @PostMapping
    public UserDto createUser(@Valid @RequestBody UserDto user) {
        return user;
    }

    // WRONG: Missing @Valid — all UserDto annotations are silently ignored.
    // @PostMapping
    // public UserDto createUser(@RequestBody UserDto user) { ... }

    // CORRECT: @Validated at class level + @Min on path variable.
    // Throws ConstraintViolationException on invalid id.
    @GetMapping("/{id}")
    public UserDto getUser(@PathVariable @Min(value = 1, message = "ID must be positive") Long id) {
        return new UserDto();
    }

    // WRONG: @Valid on path variable — does not work.
    // @GetMapping("/{id}")
    // public UserDto getUser(@PathVariable @Valid Long id) { ... }
}

// --- Primitive vs Boxed type trap ---

// WRONG: @NotNull on int is meaningless. int can never be null.
// The constraint will never fire. The DTO silently accepts any int value.
public class BrokenDto {
    @NotNull(message = "Age is required")  // dead code
    private int age;
}

// CORRECT: Use Integer (boxed) when nullability matters.
public class CorrectDto {
    @NotNull(message = "Age is required")
    @Min(value = 18, message = "Must be at least 18")
    private Integer age;
}

// io.thecodeforge — java tutorial

import javax.validation.Constraint;
import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
import javax.validation.Payload;
import java.lang.annotation.*;

@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = NotDuringMarketHoursValidator.class)
public @interface NotDuringMarketHours {
    String message() default "Cannot schedule maintenance during market hours (09:30-16:00 ET)";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

class NotDuringMarketHoursValidator
        implements ConstraintValidator<NotDuringMarketHours, String> {

    @Override
    public boolean isValid(String startTime, ConstraintValidatorContext context) {
        if (startTime == null || startTime.isBlank()) {
            return true; // let @NotNull handle nulls
        }
        // Parse "HH:mm" format; hardcoded ET zone for clarity
        String[] parts = startTime.split(":");
        int hour = Integer.parseInt(parts[0]);
        int minute = Integer.parseInt(parts[1]);
        int totalMinutes = hour * 60 + minute;

        int marketOpen = 9 * 60 + 30;   // 09:30
        int marketClose = 16 * 60;       // 16:00

        // Block if within market hours
        return totalMinutes < marketOpen || totalMinutes >= marketClose;
    }
}

// io.thecodeforge — java tutorial

import javax.validation.Valid;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotEmpty;
import java.util.List;

public class OrderRequest {

    @NotBlank(message = "Customer reference is required")
    private String customerRef;

    // BOTH annotations required: @NotEmpty for the list itself, @Valid for items
    @NotEmpty(message = "At least one order item must be provided")
    @Valid
    private List<@Valid OrderItem> items;

    // Getters and setters omitted for brevity
}

class OrderItem {

    @NotBlank(message = "SKU cannot be blank")
    private String sku;

    private int quantity;
}

// io.thecodeforge — java tutorial

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

    @PostMapping
    public ResponseEntity<?> createProduct(
            @Valid @RequestBody ProductRequest request,
            BindingResult bindingResult) {
        if (bindingResult.hasErrors()) {
            List<String> errors = bindingResult.getFieldErrors()
                    .stream()
                    .map(e -> e.getField() + ": " + e.getDefaultMessage())
                    .toList();
            return ResponseEntity.badRequest().body(errors);
        }
        // proceed with creation
        return ResponseEntity.ok("Product created");
    }
}

// io.thecodeforge — java tutorial

import org.springframework.validation.annotation.Validated;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;

@Validated
@RestController
@RequestMapping("/api/search")
public class SearchController {

    @GetMapping
    public String search(
            @RequestParam @NotBlank String query,
            @RequestParam @Min(1) int page) {
        return "Results for: " + query + " page " + page;
    }
}

// io.thecodeforge — java tutorial

@RestController
public class UserController {

    // BAD: primitive silently throws IllegalArgumentException
    @GetMapping("/user")
    public String getBad(@RequestParam int id) {
        return "user " + id;
    }

    // GOOD: wrapper + validation catches missing param gracefully
    @GetMapping("/user/v2")
    public String getGood(@Valid @RequestParam @NotNull @Min(1) Integer id) {
        return "user " + id;
    }
}

// io.thecodeforge — java tutorial

@RestController
public class UserController {

    @PostMapping("/users")
    public ResponseEntity<?> create(@Valid @RequestBody User user, BindingResult result) {
        if (result.hasErrors()) {
            return ResponseEntity.badRequest().body(
                result.getFieldErrors().stream()
                    .map(e -> e.getField() + ": " + e.getDefaultMessage())
                    .toList()
            );
        }
        return ResponseEntity.ok(userService.save(user));
    }
}

// io.thecodeforge — java tutorial

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotEmpty;
import java.util.List;

public record UserDTO(
    String name,
    @NotEmpty(message = "At least one address required")
    @Valid
    List<@jakarta.validation.constraints.NotNull Address> addresses
) {}

record Address(
    @NotEmpty String street,
    @NotEmpty String city
) {}

// io.thecodeforge — java tutorial
// 25 lines max
public class ValidationOverview {
    public static void main(String[] args) {
        String userInput = "   ";  // blank string
        if (userInput == null || userInput.trim().isEmpty()) {
            System.out.println("FAIL: Input must not be blank");
        } else {
            System.out.println("PASS: Proceed with: " + userInput);
        }
        // Why? Manual checks = error-prone, untestable, verbose
        // Spring @NotBlank does this declaratively
    }
}

// io.thecodeforge — java tutorial
// 25 lines max
public class DiscussValidation {
    public static void main(String[] args) {
        System.out.println("// Share your experience:");
        System.out.println("// 1. Worst validation bug you've seen?");
        System.out.println("// 2. Custom validator you're proud of?");
        System.out.println("// 3. How do you test validation edge cases?");
        // Open a thread below!
    }
}

// io.thecodeforge — java tutorial
// 25 lines max
public class FinalValidation {
    public static void main(String[] args) {
        System.out.println("Rule 1: Validate at controller boundaries.");
        System.out.println("Rule 2: Fail early — no silent nulls.");
        System.out.println("Rule 3: Customize when annotations aren't enough.");
        System.out.println("Rule 4: Test validation, not assumptions.");
        // Apply these and sleep better.
    }
}