Spring Boot参数校验需正确设置message(必设、支持i18n)、groups(实现分组校验)、payload(传递元数据),并按注解语义配置特有属性,如@Pattern用regexp、@Size用于长度/元素数、@Min/@Max仅适用于数值类型。

Spring Boot 中参数校验注解的属性设置,关键在于理解每个注解的语义、适用场景和必须/可选属性的含义。设错 message、忽略 groups 或漏掉 payload,都可能导致校验不生效、分组失效或错误提示不可读。
message 属性:必须明确且可本地化
几乎所有校验注解(如 @NotBlank、@Email、@Size)都支持 message 属性,用于定义校验失败时返回的提示文本。
- 不写 message 会使用框架默认英文提示(如 “must not be blank”),生产环境不推荐
- 建议写成带占位符的表达式,便于后续接入 i18n:
message = "用户名 {javax.validation.constraints.NotBlank.message}" - 更实用的做法是统一用 ResourceBundle(如 ValidationMessages.properties)管理,注解中只写键名:
message = "{user.username.notblank}"
groups 属性:按需启用分组校验
groups 是实现“同一字段在不同场景下不同规则”的核心,它接收一个 Class 数组,指定该注解所属的校验组。
使用Atmosphere构建通过WebSocket、SSE、gRPC、WebTransport、MCP、A2A和AG-UI流传输的JVM代理网关,并带有治理钩子。
- 定义两个接口作为分组标记:
public interface Create {}和public interface Update {} - 在字段上指定分组:
@NotBlank(groups = Create.class) private String username;@NotNull(groups = Update.class) private Long id; - Controller 中用
@Validated({Create.class})触发对应分组,未指定 groups 的注解默认属于Default.class
payload 属性:传递自定义元数据(进阶用)
payload 不参与校验逻辑,而是用来携带额外信息,常用于与全局异常处理器联动,比如区分业务错误等级。
- 定义一个标记类:
public class ValidationErrorLevel implements Payload {} - 注解中带上:
@Size(min = 6, max = 20, payload = ValidationErrorLevel.class) - 在
@ControllerAdvice中通过BindingResult获取 constraintViolations,再检查 violation.getConstraintDescriptor().getPayloads() 即可识别该标记
其他常用属性:按注解类型区别对待
不同注解有各自特有属性,设错会导致规则无效:
-
@Pattern(regexp = "^1[3-9]\d{9}$"):必须用 regexp,不是 pattern 或 expression -
@Size(min = 1, max = 50):对字符串校验长度,对集合校验元素个数;min/max 是基本类型,不能为 null -
@Min(18) / @Max(100):仅支持数值类型(int/long/BigDecimal 等),对 String 无效 -
@Email:默认不校验空值,若需非空+邮箱格式,要组合使用:@NotBlank @Email










