API 设计原则：RESTful 最佳实践

好的 API 让前端开发者开心，坏的 API 让人想砸键盘。

RESTful 核心原则

1. 资源导向

URL 表示资源，不是动作。

❌ /getUsers, /createUser ✅ /users

2. 使用 HTTP 方法

• GET: 获取资源
• POST: 创建资源
• PUT: 更新资源
• DELETE: 删除资源

3. 状态码要准确

• 200: 成功
• 201: 创建成功
• 400: 请求错误
• 401: 未授权
• 404: 资源不存在
• 500: 服务器错误

响应格式规范

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

版本控制

在 URL 或 Header 中体现版本：

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

分页和过滤

GET /users?page=1&limit=20&status=active

错误处理

提供清晰的错误信息：

{
  "code": 400,
  "message": "参数验证失败",
  "errors": [
    {"field": "email", "message": "格式不正确"}
  ]
}

好的 API 是文档化的，代码即文档。