Java 后端 / 系统课时

应用 Bean Validation

应用 Bean Validation

本课把输入校验从控制器中的手工判断迁移到 Jakarta Bean Validation,并覆盖标准注解、创建与更新分组、自定义密码约束及测试验证。完成后,接口可以用一致方式拒绝非法请求。

学习目标

  • 使用 Jakarta Validation 注解声明字段规则
  • 通过分组区分创建与更新场景
  • 编写并测试一个自定义约束

引入校验能力

Spring Boot 3 使用 jakarta.validation 命名空间。Web 项目通常添加 spring-boot-starter-validation,它会提供 Bean Validation API 与默认实现。

xml
<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。

Bean Validation 请求校验流程

定义分组与自定义约束

下面的完整 JUnit 5 测试同时演示创建分组、更新分组和自定义强密码约束。代码应放在已引入 spring-boot-starter-validation 与 spring-boot-starter-test 的 Spring Boot 3 项目测试目录中。

java
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.*");
        }
    }
}

运行测试:

bash
mvn -Dtest=UserCommandValidationTest test

预期输出中的时间和路径可能不同,关键结果如下:

text
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS

在控制器中选择分组

创建接口和更新接口应显式选择分组,避免同一个 DTO 在不同场景下执行错误规则。

java
@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 中执行并抛出明确的业务异常,避免校验器产生隐式查询和性能问题。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

应用 Bean Validation

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通