Spring Boot参数校验规范强调可执行的一致性约定，明确“谁来校验、在哪校验、怎么写、怎么错、怎么改”五要素；强制HTTP接口入参后端校验，统一注解使用与错误提示，配套全局异常处理与文档同步机制，并支持分组校验和豁免流程。
团队制定 Spring Boot 参数校验规范，核心不是堆砌技术细节，而是建立可执行、易理解、能落地的一致性约定。重点在于统一“谁来校验、在哪校验、怎么写、怎么错、怎么改”这五个问题。
明确校验边界与责任分工
避免“校验该不该做”的争论，直接定义强制规则：
- 所有对外暴露的 HTTP 接口（@RestController），必须对入参进行后端校验；前端校验仅作为体验优化，不作为安全依赖
- 校验逻辑只放在 Controller 层或 DTO 层，禁止在 Service 或 Mapper 层重复写 if-else 校验
- DTO 类是唯一允许添加校验注解的位置，实体类（Entity）、VO、Query 对象也按此标准执行
- 路径参数（@PathVariable）、查询参数（@RequestParam）、请求体（@RequestBody）全部纳入校验范围，不因参数形式不同而降低要求
统一注解使用标准
减少随意性，让代码一眼可读：
- 非空判断优先用 @NotBlank（String）和 @NotNull（数字/对象），不用 @NotEmpty（语义模糊，易误用）
- 长度/数量限制统一用 @Size（覆盖 String、List、Map），不用组合多个 @Min/@Max
- 密码、手机号、邮箱等格式校验，必须用 @Pattern 或 @Email，禁用自定义正则字符串硬编码在 message 中
- 每个注解必须带 中文 message，且句式统一：“{字段名} {规则说明}”，例如 “用户名不能为空”“订单ID必须大于0”
强制配套机制落地
光有注解不够，必须闭环：
- Controller 类顶部统一加 @Validated，确保路径/查询参数校验生效
- 所有 @RequestBody 参数必须加 @Valid，不加则 CI 构建失败（可通过 Checkstyle 或自定义 Maven 插件拦截）
- 全局异常处理器必须捕获 MethodArgumentNotValidException 和 BindException，返回标准错误结构：code=400、message=具体字段错误、data={“field”:“username”,“reason”:“用户名不能为空”}
- 新增或修改 DTO 时，必须同步更新对应接口的 OpenAPI 文档（如 Swagger 注解或 OpenAPI 3.0 YAML），校验规则需在文档中可查
支持演进与例外管理
留出合理弹性，防止规范僵化：
- 复杂跨字段校验（如“结束时间不能早于开始时间”）用 @Validated + 分组接口，定义 CreateCheck / UpdateCheck 等分组，并在 Controller 方法中显式指定
- 高频调用接口若实测校验成为瓶颈，可申请豁免部分非关键字段，但需在代码中标注 @SuppressWarnings("unused-validation") 并附 Jira 链接说明原因
- 团队共享一个 validation-starter 模块，封装通用注解（如 @ChineseMobile、@StrongPassword）、默认消息模板、以及适配公司日志体系的异常上报逻辑
