规范校验是什么
规范校验是把团队接口约定写成机器可执行的规则，对接口描述文件做自动检查：路径命名风格、必填字段、错误响应结构、示例有效性、是否声明版本头等。工程上通常维护一份规则集文件，在提交与合并阶段扫描，输出问题定位，让风格分歧在评审之前就被拦下，而不是靠评审人记忆规范逐条核对。
规则怎么定才不会被绕过
规则过严又没有豁免通道，团队会整体绕过检查，规则就失去权威性；规则与接口规范脱节，新约定也落不了地。可行做法是给每条规则指定负责人与严重级别，错误级别阻断合并、警告级别只提示，并允许登记带期限的例外；规范升级时先加规则观察告警量，再决定是否升为阻断，规则集自身也应版本化管理。
基本信息
| 检查对象 | 接口描述文件与示例数据，覆盖路径、参数与响应结构 |
|---|---|
| 常见规则 | 路径命名风格、必填字段、统一错误结构、版本声明 |
| 执行时机 | 提交钩子与合并请求流水线，问题定位到具体行 |
| 严重级别 | 错误阻断合并，警告提示整改，避免一刀切 |
| 演进方式 | 规则集版本化，新约定先加规则再整改存量接口 |
Spectral 规则片段
Spectral 规则片段
rules:
operation-operationId:
severity: error # 每个操作必须有唯一标识
path-kebab-case:
severity: warn # 路径使用短横线风格
error-schema-required:
severity: error # 统一错误响应结构典型使用场景
- 多人协作的接口仓库里统一风格，减少评审中的反复讨论
- 把对外开放接口的强制约定固化为检查项，防止被无意破坏
- 接口变更时自动检查是否保留既有必填字段与错误结构
- 规范升级后先加规则观察告警量，再决定是否升级为阻断
规则要有例外机制与负责人：一刀切的检查会被整体绕过，失去权威性，最后谁都不再关心检查输出。
示例数据失效却仍参与校验时，检查结果不可信，团队会对告警脱敏；示例应随接口变更同步更新并纳入用例回归。