Java 后端 / 系统课时
应用 Bean Validation
应用 Bean Validation
本课把输入校验从控制器中的手工判断迁移到 Jakarta Bean Validation,并覆盖标准注解、创建与更新分组、自定义密码约束及测试验证。完成后,接口可以用一致方式拒绝非法请求。
学习目标
- 使用 Jakarta Validation 注解声明字段规则
- 通过分组区分创建与更新场景
- 编写并测试一个自定义约束
引入校验能力
Spring Boot 3 使用 jakarta.validation 命名空间。Web 项目通常添加 spring-boot-starter-validation,它会提供 Bean Validation API 与默认实现。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>依赖生效后,控制器参数使用 @Valid 或 @Validated 即可触发校验。可执行 mvn dependency:tree,确认依赖树中存在 spring-boot-starter-validation 和 Hibernate Validator。
理解校验执行路径
请求 JSON 先绑定为 DTO,再根据控制器指定的分组执行标准约束与自定义约束。全部通过后才进入业务方法;任一约束失败都会抛出校验异常,通常由全局异常处理器转换为 HTTP 400。

定义分组与自定义约束
下面的完整 JUnit 5 测试同时演示创建分组、更新分组和自定义强密码约束。代码应放在已引入 spring-boot-starter-validation 与 spring-boot-starter-test 的 Spring Boot 3 项目测试目录中。
import jakarta.validation.Constraint;
import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;
import jakarta.validation.Payload;
import jakarta.validation.Validation;
import jakarta.validation.Validator;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Null;
import org.junit.jupiter.api.Test;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import java.util.Set;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
class UserCommandValidationTest {
interface Create {}
interface Update {}
private final Validator validator =
Validation.buildDefaultValidatorFactory().getValidator();
@Test
void createShouldRejectWeakPassword() {
UserCommand command = new UserCommand(null, "alice", "abc");
Set<String> messages = validator.validate(command, Create.class)
.stream()
.map(v -> v.getMessage())
.collect(java.util.stream.Collectors.toSet());
assertEquals(Set.of("密码至少包含一个大写字母和一个数字"), messages);
}
@Test
void updateShouldRequireId() {
UserCommand command = new UserCommand(null, "alice", "Abc123");
Set<String> messages = validator.validate(command, Update.class)
.stream()
.map(v -> v.getMessage())
.collect(java.util.stream.Collectors.toSet());
assertTrue(messages.contains("更新时必须提供用户 ID"));
}
record UserCommand(
@Null(groups = Create.class, message = "创建时不能指定用户 ID")
@NotNull(groups = Update.class, message = "更新时必须提供用户 ID")
Long id,
@NotBlank(groups = {Create.class, Update.class}, message = "用户名不能为空")
String username,
@NotBlank(groups = Create.class, message = "创建时密码不能为空")
@StrongPassword(groups = {Create.class, Update.class})
String password
) {}
@Documented
@Constraint(validatedBy = StrongPasswordValidator.class)
@Target({FIELD, METHOD, PARAMETER, ANNOTATION_TYPE, TYPE_USE})
@Retention(RUNTIME)
@interface StrongPassword {
String message() default "密码至少包含一个大写字母和一个数字";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}
public static class StrongPasswordValidator
implements ConstraintValidator<StrongPassword, String> {
@Override
public boolean isValid(String value, ConstraintValidatorContext context) {
if (value == null || value.isBlank()) {
// 空值交给 @NotBlank 处理,避免重复错误信息。
return true;
}
return value.matches(".*[A-Z].*") && value.matches(".*\\d.*");
}
}
}运行测试:
mvn -Dtest=UserCommandValidationTest test预期输出中的时间和路径可能不同,关键结果如下:
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS在控制器中选择分组
创建接口和更新接口应显式选择分组,避免同一个 DTO 在不同场景下执行错误规则。
@PostMapping("/users")
public UserResponse create(
@RequestBody @Validated(Create.class)
UserCommand command) {
return userService.create(command);
}这是片段示例,实际项目应把 Create、Update、UserCommand 放入生产代码包,而不是引用测试类。创建接口会要求 id 为空并校验密码;更新接口改用 Update.class,要求提供 id。若只写 @Valid,默认仅执行默认分组,不会自动执行这里声明的 Create 或 Update 规则。
设计校验边界
Bean Validation 适合校验格式、长度、取值范围和字段间约束,不负责查询数据库或执行业务授权。“邮箱格式是否合法”属于 DTO 校验,“邮箱是否已注册”属于 Service 业务校验,“当前用户能否修改该账号”属于权限校验。
自定义约束应保持确定、快速且无副作用。需要跨字段校验时,可把注解放在 DTO 类型上;需要访问数据库时,优先在 Service 中执行并抛出明确的业务异常,避免校验器产生隐式查询和性能问题。