RESTful API 设计最佳实践

REST（表述性状态转移）是设计 Web API 的主流风格。遵循 RESTful 规范，能让 API 清晰、可预测、易维护。

一、核心思想

REST 把一切视为"资源"，用 HTTP 方法表示对资源的操作，URL 表示资源位置。

二、URL 设计

# 好：用名词复数
GET    /users          # 获取用户列表
GET    /users/123      # 获取单个用户
POST   /users          # 创建用户
PUT    /users/123      # 更新用户
DELETE /users/123      # 删除用户

# 坏：用动词
GET    /getUsers
POST   /createUser

三、HTTP 方法的语义

• GET：获取（安全、幂等、可缓存）
• POST：创建（非幂等）
• PUT：整体更新（幂等）
• PATCH：部分更新
• DELETE：删除（幂等）

幂等性是关键：GET、PUT、DELETE 多次执行结果相同，POST 不是。客户端重试时这点很重要。

四、状态码

200 OK           成功
201 Created      创建成功
204 No Content   成功无返回（如删除）
400 Bad Request  请求格式错误
401 Unauthorized 未认证
403 Forbidden    无权限
404 Not Found    资源不存在
422 Unprocessable 实体错误（如校验失败）
500 Server Error 服务器错误

五、嵌套与关系

GET /users/123/posts        # 用户 123 的文章
GET /users/123/posts/456     # 用户的某篇文章

六、过滤、排序、分页

GET /users?role=admin&sort=-created&page=2&limit=20

• ?role=admin 过滤
• ?sort=-created 排序（- 表示降序）
• ?page=2&limit=20 分页

七、版本控制

GET /api/v1/users       # URL 路径版本（最常用）
# 或在 Header 里
Accept: application/vnd.myapp.v2+json

八、统一响应格式

{
  "code": 0,
  "message": "success",
  "data": { "id": 123, "name": "张三" }
}

九、小结

RESTful 不是强制标准，而是约定。遵循它能降低团队沟通成本、提高 API 可用性。适合大多数 CRUD 场景，复杂查询可能需要权衡。