Master Elegant Parameter Validation in Spring Boot with Hibernate Validator

Introduction

For developers, validating user input or system parameters is a routine task. Many encounter the question: How should parameter validation be written? A typical user‑registration API needs to enforce rules such as non‑empty usernames (3‑20 characters), passwords (minimum 8 characters), age (positive integer ≤ 120), and a correctly formatted email.

At first glance, simple if statements seem sufficient, but this approach quickly reveals hidden issues.

1. Problems with Traditional Validation

Developers often write validation logic directly in the controller, for example:

@RestController
@RequestMapping("/api/users")
public class UserController {
    @PostMapping("/register")
    public ResponseEntity<String> register(@RequestBody Map<String, Object> request) {
        String username = (String) request.get("username");
        if (username == null || username.length() < 3 || username.length() > 20) {
            return ResponseEntity.badRequest().body("用户名不能为空，且长度必须在3到20之间");
        }
        String password = (String) request.get("password");
        if (password == null || password.length() < 8) {
            return ResponseEntity.badRequest().body("密码不能为空，且长度至少为8个字符");
        }
        Integer age = (Integer) request.get("age");
        if (age == null || age <= 0 || age > 120) {
            return ResponseEntity.badRequest().body("年龄必须是正整数，且不能超过120");
        }
        return ResponseEntity.ok("注册成功！");
    }
}

This code suffers from:

Code redundancy : Validation logic is scattered across controllers, making maintenance difficult.

Duplicated effort : Similar checks appear in many endpoints.

Poor user experience : Inconsistent error messages force the front‑end to guess the problem.

Low extensibility : Adding new rules requires changes in many places.

While it may work for simple cases, it becomes a liability as the business grows.

2. Spring Boot Validation Mechanism

Spring Boot leverages Hibernate Validator , the reference implementation of Bean Validation, to move validation logic out of business code and declare rules via annotations.

2.1 Using Annotations for Validation

First, define a DTO that receives registration parameters:

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

Common annotations used: @NotNull: field must not be null. @Size: restrict string length. @Min and @Max: restrict numeric range. @Email: validate email format.

Then, apply @Valid in the controller:

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

The @Valid annotation tells Spring to validate the incoming request against the constraints defined in the DTO.

2.2 Unified Error Handling

If validation fails, Spring throws MethodArgumentNotValidException. The default response is not user‑friendly. A global exception handler can format errors consistently:

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

Now the client receives a clear JSON map, e.g.:

{
  "username": "用户名长度必须在3到20之间",
  "password": "密码不能为空"
}

3. Advanced Techniques for Complex Scenarios

3.1 Group Validation

Different endpoints may require different validation rules. Define marker interfaces for groups:

public interface RegisterGroup {}
public interface UpdateGroup {}

Assign groups to constraints:

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

Validate specific groups in controller methods:

@RestController
@RequestMapping("/api/users")
public class UserController {
    @PostMapping("/register")
    public ResponseEntity<String> register(@Validated(RegisterGroup.class) @RequestBody UserRequest request) {
        return ResponseEntity.ok("注册成功！");
    }

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

3.2 Custom Validation Annotation

If built‑in constraints are insufficient, create a custom annotation. Example: validating a phone number format.

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

Implement the validator:

public class PhoneValidator implements ConstraintValidator<ValidPhone, String> {
    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);
    }
}

Use the custom annotation in a DTO:

public class UserRequest {
    @ValidPhone
    private String phone;
}

Conclusion

Elegant parameter validation improves code maintainability and user experience. In Spring Boot, leveraging Hibernate Validator annotations, combined with group validation, custom constraints, and a unified exception handler, provides a concise, efficient, and extensible validation solution.