[65] Spectral（OpenAPI linter）：把接口契约变成可自动验收的门禁¶
- 原始来源：https://github.com/stoplightio/spectral
- 对应章节：第 3 章（PRD 与工程合同）、第 7 章（工程化）、第 9 章（后端架构）、第 10 章（Agent：工具合同）
一句话摘要¶
Spectral 的价值不在把 YAML 挑错字，而在于：它让 OpenAPI 这种写给人看的契约，变成能在 CI 里自动否决的合同条款。
你应该从这里带走什么（面向产品）¶
- PRD 不是文档，是合同：当你把 API 作为产品能力出售（给前端、给第三方、给 Agent 工具调用），契约必须能被自动检查，才能谈可回归。
- 风控不只在支付：接口契约不稳会直接导致计费口径漂移、权限越界、回滚困难，这些最后都会变成成本事故与信任事故。
工程落地要点（可执行）¶
- 把 OpenAPI 当作单一事实源（SSOT）：代码生成/Mock/测试都从它派生，而不是各写各的。
- 建立三层规则集（从宽到严）：
- 基础语法层：OpenAPI 是否合规、字段是否缺失。
- 一致性层：命名、分页、错误结构、幂等键、Trace header 等是否统一。
- 产品合同层：哪些字段必须有、哪些字段禁止出现、哪些变更必须是 major。
- 在 CI 里做门禁化：
- PR 提交时跑一次
spectral lint； - 合并主干前再跑一次；
- 对破坏性变更直接 fail，并在 PR 评论里给出可读的原因。
常见误用提醒¶
- 只靠 lint 不够：Spectral 能保证合同形状，但不能保证行为正确；仍需要契约测试/回归测试。
- 规则太多反而失控：一开始先做最小规则集（比如错误结构、分页、幂等、鉴权头），用事故驱动逐步加严。