REST API 设计规范

团队接口为什么总对不齐

多人协作或前后端联调时，常见问题是：URL 里塞动词、创建成功仍返回 200、错误体里带堆栈、分页 sort 直接拼进 SQL、Handler 里堆业务逻辑。这些不是「框架选错了」，而是缺少一套可对照检查的约定。

技能覆盖什么

本规范按 跨语言通用 思路组织，不绑定某一框架，但给出与 Spring、FastAPI、Express、Gin、ASP.NET 等的概念映射表，便于落地。

• 资源与 URL：名词复数、路径嵌套不超过 3 级；集合/单资源 CRUD 与 POST /orders/{id}/cancel 类动作的分工；版本优先 /api/v1/...，筛选分页走 query。
• HTTP 语义：GET/POST/PUT/PATCH/DELETE 的幂等与 Body 规则；禁止「全部 POST」。
• 状态码与响应体：2xx 不含错误信息；4xx/5xx 必须有人类可读说明；统一封装（业务码或对齐 HTTP）及列表/分页/错误结构。
• 工程结构：网关 → 入口校验 → 业务层；Handler 只负责参数与编排；全局异常映射到 401/403/404/409/422/500。
• 安全与文档：JWT/OAuth2、越权与枚举统一 404、幂等键、限流 429；接口以 OpenAPI 3.x 维护并与代码同步。

文末附有 严禁清单（如空列表返回 null、排序字段不白名单等），适合在评审或 Code Review 时逐项勾选。

适用边界

这是设计规范与检查清单，不会替你生成具体项目的 DTO 或 OpenAPI 文件；风格 A/B 的响应 JSON 示例在原文中为占位，落地时需你们选定一种并在全项目统一。业务域建模（哪些资源、哪些状态机）仍需结合产品自行定义。