后端 API 设计教程：认证、校验、错误码与幂等

文章定位：HTTP API、认证、授权、参数校验、分页、幂等和观测

核心结论

API 是客户端与服务端之间的契约。先定义资源、输入、输出和失败情形，再选择路径和方法。控制器负责协议转换，服务层负责业务规则，数据层负责持久化。

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "请求参数不合法",
    "request_id": "req_123"
  }
}

认证回答“你是谁”，授权回答“你能做什么”。前端隐藏按钮不能代替服务端权限判断。创建订单、支付和发送通知等操作应设计幂等键；分页接口要稳定排序。

测试至少覆盖成功、校验失败、权限失败、重复请求和依赖超时。错误响应不能泄露堆栈、SQL、密钥和内部路径，日志则应通过 request ID 串联请求链路。

参考资料

1 2