---
name: input-validation
when: '参数校验, 输入验证, 字段验证, 合法性校验, 入参校验, 必填, 格式校验, 参数检查, @Valid, @NotNull'
scope:
  - backend
products:
  - '*'
id: ka-pattern-input-validation
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 参数校验
  - 输入验证
  - 字段验证
  - 合法性校验
  - 入参校验
  - 必填
  - 格式校验
  - 参数检查
  - '@Valid'
  - '@NotNull'
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 必须使用 Bean Validation 注解（@NotBlank、@Size、@Min 等）声明式校验
- 禁止手写 if-else 逐字段校验（跨字段业务规则除外）
- 创建和更新必须使用分组校验（CreateGroup/UpdateGroup）
- 校验失败必须返回 400 + 具体字段名和错误消息
- 后端必须校验，禁止仅依赖前端校验
- 数组/集合参数必须校验非空且限制最大长度（防止批量攻击）
- 枚举类型参数必须校验是否为合法枚举值，禁止直接信任前端传入
- 日期参数必须指定格式（@DateTimeFormat）并校验合理性（不能是未来日期等）
- 富文本输入必须使用白名单标签过滤（如 jsoup Whitelist），禁止直接存储原始 HTML
- 正则表达式校验必须限制输入长度和复杂度，防止 ReDoS 攻击
- URL 参数必须校验协议白名单（仅允许 http/https），防止 SSRF

## 验收项
- [AC-01] 所有 DTO 字段有校验注解
- [AC-02] 创建/更新使用分组校验
- [AC-03] 校验失败返回 400 + 字段详情
- [AC-04] 无手写 if-else 参数校验
- [AC-05] 集合参数有长度限制
- [AC-06] 枚举参数校验合法值
- [AC-07] 富文本经过白名单过滤
- [AC-08] URL 参数校验协议白名单
