WebAPI 与前端契约检查
本页用于检查项目的 API 返回包、字段命名、错误处理和接口文档是否与前端契约保持一致。
检查目标
- 判断前端是否只需要面对一套稳定接口协议。
- 判断 API 实际行为、接口文档和规范页是否一致。
- 判断旧接口兼容是否被控制在明确范围内。
必查项
- API 是否默认返回
{ data, code, msg, errMsg, tid }。 - 前端消费字段是否统一为
camelCase。 - 成功返回、业务错误、系统错误是否都能稳定映射到标准包。
- 到达应用程序层的统一 JSON API 是否稳定返回 HTTP
200，并把成功、鉴权失败、业务错误和系统错误都落到code。 /api/*下的 JSON WebAPI action 是否全部使用具体 DTO、集合 DTO 或Task作为返回签名。/api/*下的 JSON WebAPI action 是否仍残留IActionResult或ActionResult<T>。- 空成功接口是否使用
Task，并与项目约定的 envelope 表现一致。 - Swagger 或其他接口文档是否体现真实返回结构，尤其是 envelope 的
data是否指向真实 DTO。 - 旧接口若仍使用其他字段风格，是否在适配层和文档中显式标注。
判定标准
- 新接口全部遵循标准包和
camelCase，判定为合规。 /api/*下的 JSON WebAPI action 全部使用具体 DTO、集合 DTO 或Task，且 Swagger 的data能映射到真实模型，判定为合规。- 若局部接口仍返回裸对象或
PascalCase字段，判定为偏差。 - 只要
/api/*下的 JSON WebAPI action 继续使用IActionResult或ActionResult<T>，判定为偏差。 - 若错误返回不带
code或tid，判定为前端契约不完整。 - 若统一 JSON API 的 HTTP 传输状态、envelope 结构或文档描述不一致，判定为不合规。
常见不合规信号
- 接口 A 返回封包，接口 B 返回裸对象。
- Swagger 显示
EnvelopMessage<T>，实际接口返回另一套字段。 - action 返回
IActionResult或ActionResult<T>，Swagger 的data退化成无类型object。 - 为了描述空成功而返回
string.Empty、匿名对象或其他占位值。 - 统一 JSON API 实际总是返回
200，Swagger 却仍暴露201、202或4xx/5xx作为对外契约。 - 前端页面里到处写兼容判断，例如既读
errMsg又读message。 - 同一系统中混用
camelCase、PascalCase和snake_case的 JSON 字段。