前后端分离后,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)
- 创建类接口可加幂等键,避免重复提交
常见错误
- 所有接口都返回 200,错误只写在 body
- 字段命名中英混用、同一含义多个名字
- 没有版本策略,一改全崩(可用
/api/v1) - 文档缺失:至少维护 OpenAPI / 示例请求