Javax Validation API的@NotEmpty与@Size注解失效问题排查

以下是针对你遇到的验证未生效问题的具体排查步骤和解决方法：

1. 确认@Valid的导入包正确 #

确保Controller方法参数上的@Valid是javax.validation.Valid（JSR标准注解），而非Spring的org.springframework.validation.annotation.Valid（该注解用于方法级验证，不适合请求体的字段验证）。

2. 必须为请求体参数添加@RequestBody注解 #

如果QueryRequest是POST请求的JSON/XML请求体，必须在参数前加上@RequestBody，否则Spring无法正确绑定请求体数据，验证自然不会触发：

@PostMapping("/execute-query")
public ResponseEntity<String> handleQuery(@Valid @RequestBody QueryRequest request) {
    // 业务逻辑
    return ResponseEntity.ok("success");
}

3. 检查QueryRequest类的注解配置 #

• 确保@NotEmpty、@Size等注解来自javax.validation.constraints包，而非其他第三方包；
• 注解必须直接标注在字段上，且字段需提供对应的getter方法（验证框架默认通过getter访问字段值）：

public class QueryRequest {
    @NotEmpty(message = "查询内容不能为空")
    @Size(max = 160, message = "查询内容长度不能超过160字符")
    private String queryContent;

    // 必须提供getter方法
    public String getQueryContent() {
        return queryContent;
    }

    // setter可选，根据需求添加
    public void setQueryContent(String queryContent) {
        this.queryContent = queryContent;
    }
}

4. 排查依赖冲突与缺失 #

spring-boot-starter-validation依赖本身包含hibernate-validator（JSR验证的具体实现），但如果父pom的依赖管理导致hibernate-validator缺失，会出现有API但无实现的情况：

• 执行mvn dependency:tree命令，检查输出中是否存在org.hibernate.validator:hibernate-validator；
• 如果缺失，手动添加依赖（适配Spring Boot 2.5.x的版本为6.2.0.Final）：

<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.2.0.Final</version>
</dependency>

• 同时确认validation-api的版本与hibernate-validator兼容，2.0.1.Final与6.2.x是兼容的，无需调整。

5. 检查是否禁用了验证自动配置 #

如果启动类添加了@SpringBootApplication(exclude = ValidationAutoConfiguration.class)，或者自定义WebMvcConfigurer时覆盖了验证相关的Bean，会导致Spring自动验证失效：

• 移除启动类中的exclude配置；
• 检查自定义WebMvc配置，确保没有替换或禁用Validator相关的Bean。

6. 尝试添加@Validated到Controller类 #

部分场景下，需要在Controller类上添加Spring的@Validated注解，才能触发方法参数的验证逻辑：

@RestController
@Validated // 添加该注解
@RequestMapping("/query")
public class QueryController {
    // 方法逻辑
}

7. 手动验证测试定位问题 #

如果上述步骤都无效，可以手动调用Validator测试验证逻辑是否正常：

@Autowired
private Validator validator;

@PostMapping("/execute-query")
public ResponseEntity<String> handleQuery(@RequestBody QueryRequest request) {
    Set<ConstraintViolation<QueryRequest>> violations = validator.validate(request);
    if (!violations.isEmpty()) {
        // 打印验证错误，确认注解是否生效
        violations.forEach(v -> System.err.println("验证错误：" + v.getMessage()));
        return ResponseEntity.badRequest().body("参数验证失败");
    }
    // 业务逻辑
    return ResponseEntity.ok("success");
}

• 如果手动验证能输出错误信息，说明Spring的自动验证拦截未生效，需检查WebMvc配置；
• 如果手动验证无错误，说明实体类的注解配置存在问题（如注解位置错误、字段无getter等）。

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