如何正确使用@Valid注解实现RestEasy/JAX-RS端点参数校验？

• 本问题完全无效。
• 保留此问题作为他人的警示案例（详见解决方案）

在RestEasy/JAX-RS端点中，当处理无嵌套对象的实体校验时，最初采用的写法如下：

@Value
public class PayloadWithNotNull {
    @NotNull Long mSomeLong; // Long为包装类型，对应基础long类型
}

...

@POST
@Path("test1")
@Produces(MediaType.APPLICATION_JSON)
public Response test1(
    final @Valid @NotNull PayloadWithNotNull payload
) {
    return ok();
}

参数payload同时标注@Valid和@NotNull，但字段mSomeLong仅标注@NotNull。针对不同请求JSON体，测试结果如下：

• 发送null → 返回400，提示信息：test1.payload must not be null
• 发送{} → 返回400，但无明确提示信息
• 发送{ "someLong": null } → 返回400，但无明确提示信息
• 发送{ "someLong": "not a long" } → 返回400，但无明确提示信息

尝试在字段上添加@Valid注解后：

@Value
public class PayloadWithValidNotNull {
    @Valid @NotNull Long mSomeLong;
}

测试结果变化为：

• 发送null → 返回400，提示信息：test1.payload must not be null
• 发送{} → 返回400，提示信息：test1.payload.someLong must not be null（表现改进）
• 发送{ "someLong": null } → 返回400，提示信息：test1.payload.someLong must not be null（表现改进）
• 发送{ "someLong": "not a long" } → 返回400，仍无明确提示信息

此前认知为@Valid仅需在处理嵌套对象时使用，但实际测试显示，无嵌套的Long字段也需添加该注解才能触发部分校验提示。因此提出问题：如何正确使用@Valid实现全场景校验，并生成有意义的错误信息？

补充说明 #

引用JAX-RS规范（31.2.2 Validating Entity Data章节）：

要校验这些实体类，请在方法参数上使用@Valid注解。

规范示例仅在方法参数上使用@Valid，并未在实体内部字段添加该注解。

本问题无效的核心原因：实体字段名与JSON请求键名不匹配。代码中字段名为mSomeLong，但请求中使用的键名是someLong，导致校验框架无法关联字段与JSON属性，进而无法生成正确的错误提示。

正确处理方式：

1. 确保实体字段与JSON键名一致，或通过@JsonProperty显式指定映射关系：

@Value
public class PayloadWithNotNull {
    @NotNull 
    @JsonProperty("someLong") // 显式绑定JSON键名
    Long mSomeLong;
}

2. 仅需在方法参数上添加@Valid即可触发所有字段的Bean Validation校验：

@POST
@Path("test1")
@Produces(MediaType.APPLICATION_JSON)
public Response test1(
    final @Valid @NotNull PayloadWithNotNull payload
) {
    return ok();
}

此时测试结果：

• 发送{} → 返回400，提示：test1.payload.someLong must not be null
• 发送{ "someLong": null } → 返回400，提示：test1.payload.someLong must not be null
• 发送{ "someLong": "not a long" } → 该场景属于Jackson序列化阶段的类型转换错误，需通过统一异常处理器捕获并生成友好提示，不属于Bean Validation的处理范畴。

总结：

• @Valid仅需添加在方法参数上，即可触发实体类所有字段的校验，非嵌套字段无需额外添加。
• 字段与JSON键名不匹配是校验提示缺失的根本原因，而非@Valid使用方式错误。
• 类型转换错误需单独通过异常处理器处理。

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