RESTful API 设计最佳实践

核心原则

RESTful 不是银弹，但遵循其原则能让 API 更易用、更易维护。

资源命名

✅ 正确做法

GET    /users          # 获取用户列表
GET    /users/123      # 获取特定用户
POST   /users          # 创建用户
PUT    /users/123      # 更新用户
DELETE /users/123      # 删除用户
GET    /users/123/posts # 获取用户的文章

❌ 错误做法

GET    /getUsers
POST   /createUser
GET    /deleteUser/123
POST   /updateUser

原则：

• 使用名词，不用动词
• 复数形式表示集合
• 小写字母，连字符分隔

HTTP 方法语义

方法	用途	幂等性
GET	读取资源	是
POST	创建资源	否
PUT	完整更新	是
PATCH	部分更新	是
DELETE	删除资源	是

状态码使用

2xx 成功

• 200 OK：通用成功
• 201 Created：资源创建成功
• 204 No Content：成功但无返回内容

4xx 客户端错误

• 400 Bad Request：请求参数错误
• 401 Unauthorized：未认证
• 403 Forbidden：无权限
• 404 Not Found：资源不存在
• 429 Too Many Requests：请求过多

5xx 服务端错误

• 500 Internal Server Error：服务器错误
• 502 Bad Gateway：网关错误
• 503 Service Unavailable：服务不可用

响应格式

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com"
  },
  "timestamp": 1711080600
}

版本控制

# URL 版本（推荐）
/api/v1/users
/api/v2/users

# Header 版本
Accept: application/vnd.myapi.v1+json

分页设计

GET /users?page=1&limit=20
GET /users?cursor=abc123&limit=20

响应：

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "hasMore": true
  }
}

过滤与排序

GET /users?status=active&role=admin&sort=-created_at

结语

好的 API 设计让开发者愉悦，坏的 API 设计让开发者想砸键盘！