技能介绍

当接口文档与实现渐行渐远

微服务拆分得越细，契约失控的代价就越高。团队常常维护着一份看起来无比精确的 OpenAPI 或 API Blueprint 文档，但后端实现的响应字段、状态码甚至语义早已悄悄变化。集成测试只能在依赖方上线后才姗姗来迟，于是 Dredd 的名字出现在告警里——集成链路因契约不一致而中断，排查成本由整个上下游共同承担。

问题的根源在于：文档与运行实例之间缺少一条持续验证的通道。

这条通道如何工作

这个技能的核心思路很直接：把 API 描述文件作为唯一的事实来源，对正在运行的服务端点执行自动化合约测试，让规范漂移在发布前就被拦截。

具体能力包括：

双格式覆盖：支持 OpenAPI 与 API Blueprint（.apib 文件）两种描述格式，适配不同团队的文档习惯。
真实端点验证：测试目标不是 mock，而是实际部署的 API，保证验证的是真实行为而非理想预期。
结构与语义双检：Dredd 不仅校验 HTTP 状态码和响应体结构，还能通过 transaction 断言深入验证关键业务字段的含义是否与描述一致。

关键步骤大致是：先准备一份描述文件（可手写，也可从 API Blueprint 官网教程或现成示例起步）；然后确认目标端点已处于运行状态；最后由 Dredd CLI 加载描述并逐条向真实端点发起请求，把断言结果汇总为测试报告。失败项会明确指向哪一个接口、哪一个字段偏离了文档。

适用边界与注意点

依赖真实环境：被测端点必须处于运行中状态，技能无法替代环境搭建，CI 流水线里建议单独准备稳定的 staging 环境。
依赖上游工具链：需要 Node.js 环境与 Dredd CLI（dredd 命令），Python 也在依赖清单中，缺一不可。
验证粒度有上限：Dredd 擅长 HTTP 层面的契约验证，不覆盖消息队列、gRPC 等非 HTTP 协议；对于深层业务逻辑的正确性，仍需配合集成测试或端到端测试。
文档质量决定上限：描述文件本身写得含糊，断言就会形同虚设——垃圾进，垃圾出，这条原则在这里完全适用。