RESTful API 设计规范：写出优雅的接口

REST 核心原则

1. 资源导向：URL 表示资源，而非操作
2. 无状态：每次请求包含完整信息
3. 统一接口：使用标准 HTTP 方法
4. 可缓存：合理利用缓存机制

URL 设计规范

✅ 正确：

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

❌ 错误：

GET    /getUsers
POST   /createUser
POST   /deleteUser/123

HTTP 状态码使用

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

响应格式规范

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三"
  },
  "timestamp": 1711612800000
}

版本控制

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

分页与过滤

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

安全建议

• 使用 HTTPS
• 实现认证授权（JWT/OAuth2）
• 限制请求频率
• 输入验证和过滤

遵循 RESTful 规范，让 API 更易用、更易维护！