RESTful API 设计指南

前后端分离成为主流后,API 就是前后端之间的"合同"。设计得好,团队协作顺畅、调用方省心;设计得差,文档越写越长,谁用谁骂。RESTful 是目前最通用的 API 设计风格,本文给出可直接落地的最佳实践。

1. REST 的核心思想

REST(Representational State Transfer)把一切都抽象为资源,每个资源有唯一的 URL,用 HTTP 方法表达对资源的操作:

HTTP 方法	语义	示例
GET	读取资源(幂等)	GET /users/42
POST	创建资源	POST /users
PUT	整体更新(幂等)	PUT /users/42
PATCH	局部更新	PATCH /users/42
DELETE	删除资源	DELETE /users/42

注意:URL 里只出现名词,动词交给 HTTP 方法。用 GET /users/42 而不是 GET /getUser。

2. 资源命名规范

一律小写,多个单词用连字符:/order-items 而非 /orderItems。
用复数名词:/users 而非 /user。
嵌套表示从属关系:/users/42/orders 表示"用户 42 的订单"。
层级不超过两层,更深的关系用查询参数表达。

3. 请求与响应设计

统一的响应结构能降低调用方的解析成本:

{
  "code": 0,
  "data": {
    "id": 42,
    "name": "Ada",
    "email": "ada@example.com",
    "created_at": "2026-07-01T10:00:00Z"
  }
}

同时要正确使用 HTTP 状态码:

2xx:成功。200 通用、201 创建成功、204 无内容。
4xx:客户端错误。400 参数错误、401 未认证、403 无权限、404 不存在。
5xx:服务端错误。500 内部错误、503 服务不可用。

不要把失败都包装成 200 + code,状态码本身就该表达语义。

4. 分页、过滤与排序

列表接口必须考虑数据量,用查询参数统一约定:

# 分页:page 从 1 开始,size 默认 20,最大 100
GET /users?page=2&size=20

# 过滤:status=active 的用户
GET /users?status=active

# 排序:按创建时间倒序
GET /users?sort=-created_at

响应里同时返回分页元信息:

{
  "data": [],
  "pagination": {
    "page": 2,
    "size": 20,
    "total": 153,
    "total_pages": 8
  }
}

5. 版本与兼容

API 一旦上线就会被调用方依赖,破坏性变更必须通过版本控制:

URL 版本号(最直观):/v1/users、/v2/users。
新字段直接加,不要改名或删字段,必要时给默认值。
废弃接口提前公告,保留至少一个版本的过渡期。

6. 用 curl 调试接口

# 带查询参数的 GET
curl "https://api.example.com/v1/users?page=1&size=10"

# POST 创建资源
curl -X POST https://api.example.com/v1/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Ada", "email": "ada@example.com"}'

# 查看响应头(状态码、缓存策略等)
curl -i https://api.example.com/v1/users/42

# 删除资源
curl -X DELETE https://api.example.com/v1/users/42

💡 学习建议:找一个真实公开 API(如 GitHub API)用 curl 逐个方法调用,再对照它的官方文档思考"为什么这么设计",是提升 API 设计感最快的方式。