Spring Boot 中多字段联合校验需通过自定义约束注解（标注在类级别）配合校验器实现，如 PasswordMatch 注解用于验证密码与确认密码一致性，单字段注解无法满足跨字段逻辑判断需求。
Spring Boot 中多字段联合校验不能靠单个字段注解（如 @NotNull 或 @Pattern）解决，因为它们只作用于本字段。真正需要的是跨字段逻辑判断，比如“密码和确认密码必须一致”“开始时间不能晚于结束时间”“当类型为 A 时，编号必须以 PR 开头”等。这类校验需通过自定义约束注解 + 校验器实现，才是优雅且可复用的方式。
定义自定义约束注解
创建一个注解，声明它用于类级别（而非字段），并指定对应的校验器类：
@Target({ElementType.TYPE}) // 必须标注在类上
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PasswordMatchValidator.class)
public @interface PasswordMatch {
String message() default "password and confirm password do not match";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}
注意：@Target(ElementType.TYPE) 表明这是类级校验，校验器才能拿到整个对象实例，从而访问多个字段。
编写对应校验器
实现 ConstraintValidator<PasswordMatch, YourFormClass>，在 isValid 方法中读取多个字段值并做逻辑判断：
public class PasswordMatchValidator implements ConstraintValidator<PasswordMatch, UserRegisterDTO> {
@Override
public boolean isValid(UserRegisterDTO dto, ConstraintValidatorContext context) {
if (dto == null) return true; // 让空对象交由 @NotNull 处理
String pwd = dto.getPassword();
String confirm = dto.getConfirmPassword();
if (pwd == null || confirm == null) return false;
return pwd.equals(confirm);
}
}
关键点：
- 校验器泛型第二个参数必须是目标 DTO 类型，确保能强转获取字段
- 不建议在
isValid中抛异常，返回false即可，错误消息由注解的message统一控制 - 若需动态提示（如高亮具体字段），可用
context.buildConstraintViolationWithTemplate()替换默认消息
在 DTO 上使用该注解
将注解加在 DTO 类名上，不是某个字段：
@PasswordMatch
public class UserRegisterDTO {
private String username;
@NotBlank private String password;
@NotBlank private String confirmPassword;
// getter/setter...
}
Controller 层保持简洁，仍用 @Valid：
@PostMapping("/register")
public Result register(@Valid @RequestBody UserRegisterDTO dto) {
return userService.register(dto);
}
进阶：支持分组与条件触发
如果联合校验只在特定场景生效（如“新增时校验手机号唯一性，编辑时不校验”），可结合分组：
- 定义分组接口：
public interface Create {} - 注解上声明：
@PasswordMatch(groups = Create.class) - Controller 中指定分组：
@Validated(Create.class)
这样避免校验逻辑污染无关流程，也便于单元测试隔离验证场景。
