api-design

接口设计

何时用

• 新增 HTTP/REST 接口，需要确定 URL 路径、请求体与响应结构时。
• 修改已有接口，要评估是否属于破坏性变更、是否需要新版本时。
• 联调阶段前端反馈"不知道错误含义"或"状态码对不上"时。
• code review 发现接口风格混乱，需要统一约定时。

核心规则

1. 资源用名词复数，HTTP 方法表达动作

规则： URL 只描述资源，增删改查全靠 HTTP 方法（GET/POST/PUT/PATCH/DELETE）区分，禁止在路径里塞动词。

为什么： AI 生成代码时极容易把动作写进路径——POST /createUser、GET /getUserById、POST /deleteOrder。这样做破坏了 REST 的统一接口约束：客户端无法通过方法推断语义，反向代理的缓存/日志规则也按 HTTP 方法设计，动词 URL 会绕开这些设施。积累下来接口命名五花八门，新人一眼看不懂哪个是幂等的、哪个有副作用。

怎么做：

• 集合资源用复数：/users、/orders、/products/{id}/reviews。
• 子资源层级不超过三级：/users/{uid}/addresses/{aid} 可接受，再深就拍平。
• 真正的「动作」（非 CRUD）用子资源或 action 后缀：POST /orders/{id}/cancel 或 POST /payments/{id}/refund，不要 POST /cancelOrder。

---

2. 状态码严格对应语义

规则： 按 HTTP 语义选状态码：2xx 成功、4xx 客户端的错、5xx 服务端的错；不用"一律 200 + { "code": 500 } "的私有协议。

为什么： AI 生成的服务端代码极常见"全部返回 200，用 body 里的 code 表示真实状态"——看起来简单，实则让所有上层基础设施失效：Nginx 的 5xx 告警触发不了，监控平台抓不到真实错误率，HTTP 客户端的重试/熔断逻辑按 2xx 判定成功而放行所有故障流量。出了事故查日志，全是绿的。

怎么做：

• 200 成功返回资源，201 创建成功（带 Location 头），204 成功但无响应体（DELETE）。
• 400 请求格式/参数错误，401 未认证，403 无权限（已认证但拒绝），404 资源不存在，409 冲突（重复创建），422 业务校验失败。
• 500 服务内部错误，502/503 上游/服务不可用，504 超时。
• 不要用 200 返回错误信息，也不要用 500 返回校验失败。

---

3. 错误响应结构统一，前端可程序化处理

规则： 所有错误响应用相同结构：code（机器可读的错误标识）、message（人类可读说明）、details（可选，字段级明细），不能每个接口各自为政。

为什么： AI 最容易犯的错是：有的接口报错返回 {"error": "invalid email"}，有的返回 {"msg": "用户不存在"}，有的直接丢出框架的原始异常 JSON。前端被迫为每个接口写专属错误解析逻辑，错误提示文案散落各处。哪天要做统一的错误埋点或国际化，根本没有抓手。

怎么做：

{
  "code": "VALIDATION_ERROR",
  "message": "请求参数不合法",
  "details": [
    { "field": "email", "message": "邮箱格式不正确" },
    { "field": "age",   "message": "年龄必须大于 0" }
  ]
}

• code 用 SCREAMING_SNAKE_CASE 枚举值，前端可 switch/map 处理。
• message 面向开发者，不直接作为用户提示（i18n 由前端按 code 查表）。
• details 仅在有字段级信息时出现，表单校验必带。

---

4. 破坏性变更走版本号

规则： 接口路径加 /v1、/v2 前缀；不兼容的改动新开版本，旧版本保留至少一个过渡期，不在原路径上直接覆盖。

为什么： AI 修改接口时惯于"直接改字段名"或"删除旧字段"——测试环境跑通了，但已上线的移动端 App、第三方集成、还没发版的前端全部一起炸。破坏性变更无声地推出去，只有故障告警才会被发现，而此时回滚服务端又会打烂已经发版的新客户端。