RESTful API 设计有哪些规范？

详细解析#

URL 设计#

URL 用名词复数表示资源，不用动词；用层级表示从属关系：

GET    /users              查询用户列表
GET    /users/123          查询单个用户
POST   /users              创建用户
PATCH  /users/123          修改用户的部分字段
DELETE /users/123          删除用户
GET    /users/123/orders   查询某个用户的订单

• 反例：/getUsers、/user/delete?id=123，动作应该由 HTTP 方法来表达
• 一般用小写字母，单词之间用连字符，如 /order-items；层级不要太深

方法与操作#

安全和幂等的含义见 GET 和 POST 的区别。

用状态码表达结果#

常用的状态码如下，细节见 HTTP 常见状态码：

• 2xx 成功：200、201、204
• 4xx 客户端错误：400 参数错误、401 未认证、403 无权限、404 资源不存在、409 冲突（如重复创建）、422 参数校验不通过、429 请求太频繁
• 5xx 服务端错误：500 内部错误、502 网关错误、503 服务暂时不可用

查询参数：过滤、排序、分页#

例如 GET /orders?status=paid&sort=-created_at&page=2&page_size=20：status=paid 用来过滤，sort=-created_at 表示按创建时间排序（- 表示降序），page 和 page_size 用来分页。分页有两种方式：

游标分页对应的 SQL 大致是 WHERE id < :last_id ORDER BY id DESC LIMIT 20，可以直接利用索引定位。

版本和错误格式#

• 版本管理：在 URL 中带上版本号，如 /v1/users，直观，也最常用；也可以放在请求头中，URL 更干净，但调试不太方便
• 统一的错误格式：包含业务错误码、错误信息，以及方便排查问题的请求 ID：

{ "code": "ORDER_NOT_FOUND", "message": "订单不存在", "request_id": "7f3c9a1e2b" }

也可以采用 RFC 9457 定义的 Problem Details 格式（application/problem+json）。

无状态和幂等#

• 无状态：每个请求都携带处理所需的全部信息（比如鉴权令牌），服务端不依赖上一次请求留下的上下文，方便水平扩展
• 幂等：GET、PUT、DELETE 重复执行的效果一样，可以放心重试；POST 不幂等，超时重试可能导致重复下单。常见做法是客户端为每次操作生成一个唯一的幂等键（如放在 Idempotency-Key 请求头里），服务端记录处理结果，遇到重复的请求直接返回第一次的结果

实践中的折中#

有些业务动作很难用增删改查表达，可以设计成动作或子资源，比如用 POST /orders/123/cancel 取消订单，用 POST /orders/123/payments 创建一条支付记录来表示支付。

和 GraphQL、gRPC 对比#

用 OpenAPI 描述接口#

用 OpenAPI 规范（前身是 Swagger 规范）描述接口的路径、参数和响应结构，可以自动生成文档（如 Swagger UI）、客户端代码和 Mock 数据，也能用来校验请求参数。

面试官可能追问#

易错点#

• PUT 是整体替换，请求里没传的字段按语义会被清空；只改部分字段用 PATCH
• 不要用 GET 做修改操作：GET 请求可能被缓存、被预加载，或者被爬虫访问
• REST 是一种设计风格，不是强制标准，团队内部保持一致比追求"纯粹"更重要