Spring Boot如何确保每个字段仅返回首个校验错误？

问题根源 #

默认情况下，Jakarta Bean Validation使用NORMAL校验模式，会执行字段上的所有约束规则，哪怕前面的规则已经失败。同时BindingResult中的FieldErrors顺序不一定和注解声明顺序一致，导致你原有的控制器逻辑可能无法正确捕获首个错误。

最优解决方案：启用FAIL_FAST校验模式 #

通过设置fail-fast=true，让校验器在字段的第一个约束失败时立即停止该字段的后续校验，从根源上避免单个字段出现多条错误信息。

方式1：配置文件全局生效 #

在application.properties或application.yml中添加配置：

# application.properties
jakarta.validation.fail-fast=true

# application.yml
jakarta:
  validation:
    fail-fast: true

方式2：编程式配置全局生效 #

如果需要更灵活的配置，可以通过Spring配置类自定义Validator：

import jakarta.validation.Validation;
import jakarta.validation.Validator;
import jakarta.validation.ValidatorFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ValidationConfig {
    @Bean
    public Validator validator() {
        ValidatorFactory factory = Validation.byDefaultProvider()
                .configure()
                .failFast(true)
                .buildValidatorFactory();
        return factory.getValidator();
    }
}

控制器逻辑优化（可选） #

如果启用FAIL_FAST后仍需确保错误顺序严格匹配注解声明顺序，可以调整控制器中的错误处理逻辑，按预设的约束优先级筛选首个错误：

@PostMapping
public ResponseEntity<?> createRecord(@Valid @RequestBody ContactRequest contactRequest, BindingResult result) {
    if (result.hasErrors()) {
        Map<String, String> errors = new HashMap<>();

        // 定义字段的校验规则优先级顺序
        Map<String, List<Class<?>>> fieldConstraintPriority = Map.of(
                "name", List.of(NotBlank.class, Size.class),
                "email", List.of(NotBlank.class, Email.class),
                "message", List.of(NotBlank.class, Size.class)
        );

        // 按优先级查找每个字段的首个错误
        fieldConstraintPriority.forEach((field, constraints) -> {
            for (Class<?> constraint : constraints) {
                FieldError error = result.getFieldError(field, constraint.getSimpleName());
                if (error != null) {
                    errors.put(field, error.getDefaultMessage());
                    break;
                }
            }
        });

        // 兜底处理未配置优先级的字段错误
        result.getFieldErrors().forEach(error -> {
            errors.putIfAbsent(error.getField(), error.getDefaultMessage());
        });

        return ResponseEntity.badRequest().body(Map.of(
                "status", false,
                "message", "Validation failed",
                "errors", errors));
    }

    // 后续业务逻辑...
}

效果验证 #

启用FAIL_FAST后，当name字段为空时，@NotBlank校验失败后会立即停止该字段的@Size校验，BindingResult中只会包含"Name is required"这一条错误，控制器返回的响应也只会保留该字段的首个错误信息。

内容的提问来源于stack exchange，提问作者Ali Zain