api-designlisted

# 接口设计 ## 何时用 - 新增 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。前端被迫为每个接口写专属错误解析逻辑，错误提示文案散落各处。哪天要做统一的错误埋点或国际化，根本没有抓手。 **怎么做：**