后端参数校验框架使用

后端参数校验是接口安全的第一道防线，但很多团队对校验框架的使用停留在“有就行”的阶段，导致重复代码泛滥、异常信息泄露、校验规则散落各处。真正的问题不是“要不要校验”，而是“怎么校验才能既安全又干净”。直接讲做法。

参数校验的核心不是注解，是分层

很多人一上来就研究@NotNull、@NotEmpty这些注解怎么用，但忽略了校验应该发生在哪一层。如果校验逻辑直接写在Controller里，业务层和服务层复用接口时就会裸奔。正确的做法是把校验严格分层：Controller层只做基础的类型和格式校验，业务层做业务规则校验，数据访问层做唯一性等存储约束校验。这样每一层各司其职，不会出现“Controller里校验了库存是否充足”这种越界代码。

基础校验用标准注解，别自己造轮子

Java生态里Bean Validation 2.0已经是事实标准，Hibernate Validator作为参考实现，内置的注解足够覆盖90%的场景。常见注解包括@NotNull、@NotEmpty、@NotBlank、@Size、@Min、@Max、@Email、@Pattern等。一个典型的DTO校验写法如下：

public class UserRegisterDTO {
    
    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度需在3-20个字符之间")
    private String username;
    
    @NotBlank(message = "密码不能为空")
    @Size(min = 8, max = 32, message = "密码长度需在8-32个字符之间")
    @Pattern(regexp = "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).+$", 
             message = "密码必须包含大小写字母和数字")
    private String password;
    
    @NotBlank(message = "手机号不能为空")
    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
    private String mobile;
    
    @Email(message = "邮箱格式不正确")
    private String email;
}

关键细节：message属性一定要写清楚，不要用默认的英文提示。用户看到“may not be null”只会觉得系统不专业。message可以抽取到国际化资源文件中，用{key}的方式引用，方便统一管理和多语言支持。

分组校验解决“同一个DTO不同场景”的难题

一个DTO在新增和修改场景下校验规则往往不同。新增时ID为空，修改时ID必填。这时候分组校验就派上用场了。定义两个标记接口：

public interface CreateGroup {}
public interface UpdateGroup {}

在DTO字段上指定分组：

public class UserDTO {
    
    @Null(groups = CreateGroup.class, message = "新增时ID必须为空")
    @NotNull(groups = UpdateGroup.class, message = "修改时ID不能为空")
    private Long id;
    
    @NotBlank(groups = {CreateGroup.class, UpdateGroup.class}, message = "用户名不能为空")
    private String username;
}

Controller里使用@Validated注解指定分组：

@PostMapping("/create")
public Result create(@Validated(CreateGroup.class) @RequestBody UserDTO dto) {
    // 业务逻辑
}

@PutMapping("/update")
public Result update(@Validated(UpdateGroup.class) @RequestBody UserDTO dto) {
    // 业务逻辑
}

分组校验让一个DTO适配多个场景，避免为每个场景创建一堆相似的DTO类，减少了代码冗余。

嵌套校验必须加@Valid，否则内层对象不会被校验

这是最容易踩的坑。当DTO里包含另一个对象时，光在外层加@Validated不会自动校验内层对象。必须在嵌套对象字段上加@Valid注解：

public class OrderDTO {
    
    @NotNull(message = "收货地址不能为空")
    @Valid  // 这个注解不能少，否则AddressDTO里的校验全部失效
    private AddressDTO address;
}

public class AddressDTO {
    @NotBlank(message = "省份不能为空")
    private String province;
    
    @NotBlank(message = "城市不能为空")
    private String city;
    
    @NotBlank(message = "详细地址不能为空")
    private String detail;
}

同理，集合类型的嵌套校验也需要@Valid，比如List<OrderItemDTO>，每个元素都会被校验到。

自定义校验注解处理特殊业务规则

内置注解处理不了所有场景，比如“用户状态只能是1、2、3中的一个”、“身份证号必须合法”。这时候需要自定义校验注解。以枚举值校验为例：

@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = EnumValueValidator.class)
public @interface EnumValue {
    String message() default "参数值不在允许范围内";
    Class[] groups() default {};
    Class[] payload() default {};
    Class> enumClass();
    String method() default "name";
}

public class EnumValueValidator implements ConstraintValidator {
    
    private Set

服务指南

帮助中心