技能介绍

要解决什么问题

在对接 REST API 时，服务端返回结构往往只是隐性约定：文档没写全、后端改字段没通知、前端或测试脚本按旧结构写死，于是等到运行期才出现解析失败、空值、类型错误，甚至把脏数据写进数据库。这类问题很难只靠人工 review 发现，因为需要同时核对 实际响应 与 模式定义，并识别文档外字段和类型漂移。

验证器如何工作

REST API 响应模式验证器 用 Ajv 把真实接口响应当作待验证数据，按 JSON Schema 执行校验。它可以提取 OpenAPI 3.x 中的 schema 定义，对响应做结构化检查，重点发现两类问题：未文档化字段，即响应里多出了 schema 未声明的属性；类型不匹配，例如声明为 string 却返回 number/object，或声明为 array 却返回 object。

典型流程是：先准备或抽取目标接口的 JSON Schema，再对真实响应执行验证，并把 Ajv 的错误信息转换为可定位的诊断结果。对工程实践来说，可以把这一步放进 CI、接口回归或联调排查流程：当响应偏离契约时，优先暴露字段漂移，而不是等到下游解析报错。

适用边界与注意点

它适合 Node.js 环境下的接口契约校验和 schema 回归，不负责自动修复 API，也不能替代高质量的 schema 维护。若 schema 本身写得过宽、过严或来源不一致，验证结果同样会失真。上游 Ajv 支持多版本 JSON Schema；draft-04 需要额外安装 ajv-draft-04，并要求 Node.js 18.x 及以后版本。对于认证复杂、响应不稳定、依赖服务端时序的请求，还应结合请求准备和重试策略。