Elegant Parameter Validation in Spring Boot with Hibernate Validator

Validating user input is a routine task for developers. Writing manual if checks in controllers quickly leads to redundant, hard‑to‑maintain code and poor user experience.

Traditional validation suffers from code duplication, scattered logic, inconsistent error messages, and low extensibility.

Spring Boot solves these problems by integrating Hibernate Validator , the reference implementation of Bean Validation. Validation rules are declared via annotations on DTO fields, and the framework automatically checks them.

Example DTO with common constraints:

@Data
public class UserRegistrationRequest {
    @NotNull(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度必须在3到20之间")
    private String username;

    @NotNull(message = "密码不能为空")
    @Size(min = 8, message = "密码长度至少为8个字符")
    private String password;

    @NotNull(message = "年龄不能为空")
    @Min(value = 1, message = "年龄必须是正整数")
    @Max(value = 120, message = "年龄不能超过120")
    private Integer age;

    @Email(message = "邮箱格式不正确")
    private String email;
}

The controller simply uses @Valid to trigger validation:

@RestController
@RequestMapping("/api/users")
public class UserController {
    @PostMapping("/register")
    public ResponseEntity
register(@Valid @RequestBody UserRegistrationRequest request) {
        return ResponseEntity.ok("注册成功！");
    }
}

When validation fails, Spring throws MethodArgumentNotValidException . A global exception handler can format the errors into a clean JSON map:

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity
> handleValidationException(MethodArgumentNotValidException ex) {
        Map
errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(error -> {
            errors.put(error.getField(), error.getDefaultMessage());
        });
        return ResponseEntity.badRequest().body(errors);
    }
}

Advanced techniques include validation groups for different API scenarios and custom validation annotations.

Group validation example:

public interface RegisterGroup {}
public interface UpdateGroup {}

public class UserRequest {
    @NotNull(groups = RegisterGroup.class, message = "用户名不能为空")
    @Size(min = 3, max = 20, groups = RegisterGroup.class, message = "用户名长度必须在3到20之间")
    private String username;

    @NotNull(groups = RegisterGroup.class, message = "密码不能为空")
    private String password;

    @Email(groups = UpdateGroup.class, message = "邮箱格式不正确")
    private String email;

    @Min(value = 1, groups = UpdateGroup.class, message = "年龄必须是正整数")
    private Integer age;
}

Controller usage with groups:

@PostMapping("/register")
public ResponseEntity
register(@Validated(RegisterGroup.class) @RequestBody UserRequest request) {
    return ResponseEntity.ok("注册成功！");
}

@PutMapping("/update")
public ResponseEntity
update(@Validated(UpdateGroup.class) @RequestBody UserRequest request) {
    return ResponseEntity.ok("更新成功！");
}

Custom annotation example for phone numbers:

@Documented
@Constraint(validatedBy = PhoneValidator.class)
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ValidPhone {
    String message() default "手机号格式不正确";
    Class
[] groups() default {};
    Class
[] payload() default {};
}

public class PhoneValidator implements ConstraintValidator
{
    private static final String PHONE_REGEX = "^1[3-9]\\d{9}$";
    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        return value != null && value.matches(PHONE_REGEX);
    }
}

Applying the custom annotation:

public class UserRequest {
    @ValidPhone
    private String phone;
}

By extracting validation logic to annotations, using groups, creating custom constraints, and handling errors globally, developers achieve clean, maintainable, and user‑friendly parameter validation in Spring Boot applications.