RESTful API 设计规范：打造优雅的接口

REST 核心原则

REST (Representational State Transfer) 是一种架构风格，强调资源导向和无状态通信。

URL 设计规范

# ✅ 好的设计
GET    /users          # 获取用户列表
GET    /users/123      # 获取特定用户
POST   /users          # 创建用户
PUT    /users/123      # 更新用户
DELETE /users/123      # 删除用户

# ❌ 避免这样
GET    /getUsers
POST   /createUser
GET    /deleteUser/123

使用名词而非动词

• 资源用名词：/users, /articles, /comments
• 操作用 HTTP 方法：GET, POST, PUT, DELETE

状态码正确使用

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

版本控制

/api/v1/users
/api/v2/users

过滤、排序、分页

GET /users?role=admin&sort=created_at&order=desc&page=2&limit=20

响应格式统一

{
  "code": 200,
  "message": "success",
  "data": {...},
  "timestamp": 1711008000
}

好的 API 设计让前后端协作更顺畅！