RESTful API 设计要点与常见错误

前后端分离后,API 就是合同。合同写清楚,联调少吵架。本文总结 REST 设计里最实用的约定和踩坑点。

资源导向,而不是动作导向

# 更 REST
GET    /api/orders
GET    /api/orders/123
POST   /api/orders
PATCH  /api/orders/123
DELETE /api/orders/123

# 不推荐
POST /api/getOrderList
POST /api/deleteOrder

统一响应结构

{
  "code": 0,
  "message": "ok",
  "data": {"id": 123, "status": "paid"}
}

错误时也返回可机读的 code 和人类可读的 message,并配上合适 HTTP 状态码(400/401/403/404/500)。

分页、过滤、排序

GET /api/orders?status=paid&page=1&page_size=20&sort=-created_at

幂等与安全

  • GET 不应改数据
  • 删除/更新要鉴权,防越权(不能只信前端传的 user_id)
  • 创建类接口可加幂等键,避免重复提交

常见错误

  1. 所有接口都返回 200,错误只写在 body
  2. 字段命名中英混用、同一含义多个名字
  3. 没有版本策略,一改全崩(可用 /api/v1)
  4. 文档缺失:至少维护 OpenAPI / 示例请求

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注