Spring WebFlux Bean Validation 失效问题求助

我来帮你搞定这个问题——之前我也踩过类似的坑，核心原因是WebFlux 对响应式类型（Mono/Flux）的验证逻辑和普通 Spring MVC 不一样：你直接把 @Valid 标注在 Mono<Ticket> 上，Spring 并不会自动验证包裹在里面的 Ticket 对象，自然也不会触发你写的错误处理逻辑。

下面是具体的修复步骤，包含 Kotlin 和 Java 示例：

1. 先确认依赖齐全 #

首先确保你的项目已经引入了 Spring Boot 的验证 starter，这是 Bean Validation 生效的基础：

• Maven 依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

• Gradle 依赖：

implementation 'org.springframework.boot:spring-boot-starter-validation'

2. 修正控制器的参数标注 #

你需要做两个关键修改：

• 给控制器类添加 @Validated 注解，启用方法级别的验证支持
• 把 @Valid 标注在 Mono 的泛型参数上（也就是内部的 Ticket 对象），告诉 Spring 要验证响应式类型包裹的具体对象

Kotlin 控制器示例 #

@RestController
@Validated // 必须添加这个注解
class TicketController(private val ticketRepository: TicketRepository) {

    @PostMapping("tickets")
    fun create(@RequestBody ticketMono: Mono<@Valid Ticket>): Mono<Ticket> {
        return ticketMono.flatMap { ticketRepository.save(it) }
            // 捕获验证失败抛出的 ConstraintViolationException，转换成你需要的错误
            .onErrorMap(ConstraintViolationException::class.java) {
                RuntimeException("验证失败：${it.message}")
            }
    }
}

Java 控制器示例 #

@RestController
@Validated // 必须添加这个注解
public class TicketController {

    private final TicketRepository ticketRepository;

    public TicketController(TicketRepository ticketRepository) {
        this.ticketRepository = ticketRepository;
    }

    @PostMapping("tickets")
    public Mono<Ticket> create(@RequestBody Mono<@Valid Ticket> ticketMono) {
        return ticketMono.flatMap(ticketRepository::save)
                .onErrorMap(ConstraintViolationException.class, 
                            ex -> new RuntimeException("验证失败：" + ex.getMessage()));
    }
}

3. 给实体类添加正确的验证注解 #

注意在 Kotlin 中，必须用 @field: 来指定注解作用于字段，否则 Bean Validation 无法识别这些规则：

Kotlin 实体类示例 #

data class Ticket(
    @field:NotBlank(message = "邮箱不能为空")
    @field:Email(message = "邮箱格式无效")
    val email: String,

    @field:NotBlank(message = "姓名不能为空")
    val name: String,

    @field:NotBlank(message = "留言内容不能为空")
    val message: String
)

Java 实体类示例 #

public class Ticket {

    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式无效")
    private String email;

    @NotBlank(message = "姓名不能为空")
    private String name;

    @NotBlank(message = "留言内容不能为空")
    private String message;

    // 别忘了添加 getter 和 setter
}

4. 可选：全局异常处理（更优雅的错误响应） #

如果不想在每个控制器方法里都处理验证异常，可以添加全局异常处理器，统一返回标准的 400 错误响应：

Kotlin 全局处理器示例 #

@RestControllerAdvice
class GlobalValidationExceptionHandler {

    @ExceptionHandler(ConstraintViolationException::class)
    fun handleValidationError(ex: ConstraintViolationException): ResponseEntity<Map<String, String>> {
        // 把验证错误转换成键值对，方便客户端解析
        val errorMap = ex.constraintViolations.associate {
            it.propertyPath.toString() to it.message
        }
        return ResponseEntity.badRequest().body(errorMap)
    }
}

这样当你发送你提供的 curl 请求时，验证会被立即触发：

curl --request POST \
--url http://localhost:8080/tickets \
--header 'content-type: application/json' \
--data '{ "email": "", "name": "", "message": "" }'

此时会返回包含所有验证错误的 400 响应，或者触发你在 onErrorMap 中定义的错误逻辑。

内容的提问来源于stack exchange，提问作者Jan Wytze