工程效率与质量 / 进阶

给 API 错误一个稳定契约：别再只返回 message

设计可被前端、日志和监控共同理解的错误结构，让失败既能展示给用户，也能快速定位。

7 分钟API · 错误处理 · 契约设计 · 可观测性

错误码比文案更稳定

message 会修改、会翻译，也可能被网关替换，不能作为客户端分支判断的依据。为可预期的业务失败提供稳定 code，同时保留人类可读的 message 和用于关联日志的 requestId。

EXAMPLE / 01API

{
  "error": {
    "code": "ORDER_STOCK_NOT_ENOUGH",
    "message": "库存不足，请调整购买数量",
    "requestId": "req_01HQ...",
    "details": { "skuId": "sku_42" }
  }
}

区分预期失败与系统故障

参数错误、资源冲突和权限不足属于可预期失败，应映射到明确的 4xx 状态。数据库断连或未捕获异常属于系统故障，返回通用 500，同时在服务端记录完整堆栈。不要把内部异常文本直接暴露给调用方。

400：请求结构或字段不合法；401/403：身份缺失或权限不足；404：目标资源不存在；409：状态冲突或幂等键重复；500：未预期的服务端故障。

用契约测试防止漂移

在 OpenAPI 中定义错误模型，为典型失败路径写集成测试，并校验 code、状态码和 requestId。新增错误码要经过评审，废弃错误码要保留迁移期。这样前端不会在某次后端重构后突然失去分支处理。

按错误码聚合比按 message 搜索可靠，也更容易为同类业务失败建立指标和告警。