Spring Boot Validation with Bean Validation API: The Architect's Guide

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;
}