WebAPI 与前端契约检查
本页用于检查项目的 API 返回包、字段命名、错误处理和接口文档是否与前端契约保持一致。
检查目标
- 判断前端是否只需要面对一套稳定接口协议。
- 判断 API 实际行为、接口文档和规范页是否一致。
- 判断旧接口兼容是否被控制在明确范围内。
必查项
- API 是否默认返回
{ data, code, msg, errMsg, tid }。 - 前端消费字段是否统一为
camelCase。 - 成功返回、业务错误、系统错误是否都能稳定映射到标准包。
- Swagger 或其他接口文档是否体现真实返回结构。
- 旧接口若仍使用其他字段风格，是否在适配层和文档中显式标注。
判定标准
- 新接口全部遵循标准包和
camelCase，判定为合规。 - 若局部接口仍返回裸对象或
PascalCase字段，判定为偏差。 - 若错误返回不带
code或tid，判定为前端契约不完整。 - 若文档与实际接口结构不一致，判定为不合规。
常见不合规信号
- 接口 A 返回封包，接口 B 返回裸对象。
- Swagger 显示
EnvelopMessage<T>，实际接口返回另一套字段。 - 前端页面里到处写兼容判断，例如既读
errMsg又读message。 - 同一系统中混用
camelCase、PascalCase和snake_case的 JSON 字段。