RESTful API 设计规范：让接口更优雅

核心原则

RESTful API 设计遵循以下原则：

1. 资源导向：URL 表示资源，而非动作
2. 无状态：每个请求包含所有必要信息
3. 统一接口：使用标准 HTTP 方法
4. 可缓存：合理利用 HTTP 缓存

URL 设计规范

✅ 正确示例

GET    /users          # 获取用户列表
GET    /users/123      # 获取单个用户
POST   /users          # 创建用户
PUT    /users/123      # 更新用户（全量）
PATCH  /users/123      # 更新用户（部分）
DELETE /users/123      # 删除用户
GET    /users/123/posts # 获取用户的帖子

❌ 错误示例

GET    /getUsers
POST   /createUser
POST   /deleteUser/123

响应格式规范

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

状态码使用

• 200 OK：成功
• 201 Created：创建成功
• 400 Bad Request：请求参数错误
• 401 Unauthorized：未授权
• 403 Forbidden：禁止访问
• 404 Not Found：资源不存在
• 500 Internal Server Error：服务器错误

版本控制

# URL 路径版本
/api/v1/users

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

分页与过滤

GET /users?page=1&limit=20&sort=-created_at&status=active

良好的 API 设计能让前后端协作更高效，降低维护成本！