RESTful API 设计最佳实践

REST 核心原则

REST 是一种架构风格，强调资源的状态转移。好的 API 设计应该直观、一致、易扩展。

URL 设计规范

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

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

HTTP 状态码正确使用

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

版本控制

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

响应格式统一

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

分页与过滤

GET /users?page=1&limit=20&sort=created_at&order=desc

安全考虑

1. 使用 HTTPS
2. 实现认证授权（JWT/OAuth2）
3. 限制请求频率
4. 输入验证和 sanitization

好的 API 设计能让前端开发更高效，维护成本更低！