Spring Boot 参数校验：@Valid 与自定义注解

参数校验是 API 开发的基本要求。本文介绍 Spring Boot 参数校验的实现。

基本校验

添加依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

常用校验注解

public class UserDTO {
    @NotBlank(message = "姓名不能为空")
    @Size(min = 2, max = 50, message = "姓名长度2-50")
    private String name;
    
    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;
    
    @NotNull(message = "年龄不能为空")
    @Min(value = 1, message = "年龄最小1岁")
    @Max(value = 150, message = "年龄最大150岁")
    private Integer age;
    
    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
    private String phone;
}

Controller 使用

@PostMapping
public ApiResponse<User> create(@Valid @RequestBody UserDTO dto) {
    return ApiResponse.success(userService.create(dto));
}

分组校验

public interface Create {}
public interface Update {}

public class UserDTO {
    @NotBlank(groups = {Create.class, Update.class})
    private String name;
    
    @Null(groups = Create.class)
    @NotNull(groups = Update.class)
    private Long id;
}

@PostMapping
public void create(@Validated(Create.class) @RequestBody UserDTO dto) {}

@PutMapping
public void update(@Validated(Update.class) @RequestBody UserDTO dto) {}

自定义校验注解

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

public class PhoneValidator implements ConstraintValidator<Phone, String> {
    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (value == null) return true;
        return value.matches("^1[3-9]\\d{9}$");
    }
}

嵌套校验

public class OrderDTO {
    @Valid
    @NotNull
    private UserDTO user;
    
    @Valid
    @NotEmpty
    private List<OrderItemDTO> items;
}

最佳实践

1. DTO 校验：在 DTO 层校验，不要在 Service 层
2. 分组校验：不同操作使用不同校验规则
3. 自定义注解：复用校验逻辑
4. 统一异常处理：配合 @ControllerAdvice 处理校验异常

总结

Spring Boot Validation 提供了强大的参数校验功能。通过注解和自定义校验器，可以轻松实现参数校验。