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

REST 核心原则

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

HTTP 方法语义

方法	用途	幂等性
GET	获取资源	是
POST	创建资源	否
PUT	更新资源（全量）	是
PATCH	更新资源（部分）	否
DELETE	删除资源	是

URL 设计规范

✅ 推荐：

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

❌ 避免：

GET /getUsers
POST /createUser
GET /deleteUser/123

状态码使用

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

响应格式规范

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

版本控制

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

分页与过滤

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

遵循这些规范，让你的 API 更易用、更专业！