RESTful API 设计规范与最佳实践

REST 核心原则

REST（Representational State Transfer）是一种架构风格，强调：

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

URL 设计规范

✅ 正确：

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

❌ 错误：

GET /getUsers
POST /createUser
GET /deleteUser/123

HTTP 状态码使用

• 200 OK：成功
• 201 Created：资源创建成功
• 400 Bad Request：客户端错误
• 401 Unauthorized：未授权
• 404 Not Found：资源不存在
• 500 Internal Server Error：服务器错误

响应格式规范

{
  "success": true,
  "data": { ... },
  "message": "操作成功"
}

错误响应：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "邮箱格式不正确"
  }
}

版本控制

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

分页与过滤

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

遵循这些规范能让 API 更易用、易维护。