在 Spring Boot 3 的 WebFlux 响应式环境中，@ExceptionHandler 无法捕获 @Valid 失败的校验异常，必须使用 WebExceptionHandler 并显式设置 @Order(Ordered.HIGHEST_PRECEDENCE) 才能正确拦截并返回结构化验证错误。
在 spring boot 3 的 webflux 响应式环境中，`@exceptionhandler` 无法捕获 `@valid` 失败的校验异常，必须使用 `webexceptionhandler` 并显式设置 `@order(ordered.highest_precedence)` 才能正确拦截并返回结构化验证错误。
Spring Boot 3（基于 Spring Framework 6）全面转向响应式编程模型，WebFlux 的异常处理机制与传统的 Spring MVC 有本质区别：@ControllerAdvice + @ExceptionHandler 仅适用于阻塞式控制器（如 @RestController 中的同步方法），而对 Mono/Flux 返回值的方法无效。当 @Valid @RequestBody 校验失败时，WebFlux 实际抛出的是 WebExchangeBindException（而非 MVC 中的 MethodArgumentNotValidException），该异常由底层 WebHandler 链处理，需通过 WebExceptionHandler 进行响应式拦截。
✅ 正确实现：自定义 WebExceptionHandler
以下是一个生产就绪的验证错误处理器示例，支持 JSON 格式、字段级错误映射，并确保优先级最高：
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.RequiredArgsConstructor;
import lombok.SneakyThrows;
import lombok.extern.slf4j.Slf4j;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.support.WebExchangeBindException;
import org.springframework.web.server.ServerWebExchange;
import org.springframework.web.server.WebExceptionHandler;
import reactor.core.publisher.Mono;
import java.util.Map;
import java.util.Optional;
import java.util.stream.Collectors;
@Slf4j
@Order(Ordered.HIGHEST_PRECEDENCE) // ⚠️ 关键：必须显式设置最高优先级
@RestControllerAdvice // 可选，但建议保留以兼容其他注解语义
@RequiredArgsConstructor
public class ValidationHandler implements WebExceptionHandler {
private final ObjectMapper objectMapper;
@Override
@SneakyThrows
public Mono<Void> handle(ServerWebExchange exchange, Throwable throwable) {
if (throwable instanceof WebExchangeBindException bindException) {
// 构建字段名 → 错误消息的 Map
Map<String, String> errors = bindException.getBindingResult()
.getFieldErrors()
.stream()
.collect(Collectors.toMap(
FieldError::getField,
error -> Optional.ofNullable(error.getDefaultMessage())
.orElse("invalid value")
));
// 设置响应状态与类型
exchange.getResponse().setStatusCode(HttpStatus.BAD_REQUEST);
exchange.getResponse().getHeaders().setContentType(MediaType.APPLICATION_JSON);
// 写入 JSON 响应体
byte[] responseBytes = objectMapper.writeValueAsBytes(errors);
return exchange.getResponse()
.writeWith(Mono.just(exchange.getResponse().bufferFactory().wrap(responseBytes)));
}
// 非验证异常，继续向上传播
return Mono.error(throwable);
}
}? 必备前提条件
依赖已引入：确认 spring-boot-starter-validation 在 classpath 中（Spring Boot 3 默认启用 Jakarta Bean Validation）。
-
DTO 注解正确：使用 jakarta.validation.constraints.*（非 javax.*），例如：
import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.Size; public record OrganizationDto( @NotBlank(message = "组织名称不能为空") @Size(max = 100, message = "组织名称不能超过100字符") String name ) {} -
Controller 保持简洁：无需额外配置，@Valid + Mono 自动触发校验：
@PostMapping("/create") public Mono<ResponseEntity<Organization>> create(@Valid @RequestBody OrganizationDto dto) { return organizationService.create(dto).map(ResponseEntity::ok); }
⚠️ 注意事项与最佳实践
- @Order 不可省略：若未设置 @Order 或值不够高（如 Ordered.LOWEST_PRECEDENCE），该处理器将被默认的 ResponseStatusExceptionHandler 等覆盖，导致静默失效。
-
避免 @SneakyThrows 生产滥用：虽简化代码，但掩盖了潜在的 JsonProcessingException。更健壮的做法是捕获并记录：
} catch (JsonProcessingException e) { log.error("Failed to serialize validation errors", e); return Mono.error(new ServerWebExchangeException("Internal serialization error", exchange)); } - 扩展性建议：可进一步封装为通用错误响应体（如 ErrorResponse），支持错误码、时间戳、路径等字段，便于前端统一处理。
- 全局异常兜底：此处理器仅处理 WebExchangeBindException；其他异常（如业务逻辑异常）仍需配合 @ControllerAdvice + @ExceptionHandler 补充。
✅ 验证效果
发送非法请求：
POST /organizations/create
Content-Type: application/json
{
"name": null
}将得到清晰、轻量的响应：
{
"name": "组织名称不能为空"
}这不仅满足 API 规范，也极大提升了前端调试效率——告别空 400 Bad Request，真正实现“失败即可见”。
