RESTful API 设计的 6 个核心原则

1. 使用正确的 HTTP 方法

• GET - 获取资源（幂等、安全）
• POST - 创建资源
• PUT - 更新资源（幂等）
• PATCH - 部分更新
• DELETE - 删除资源（幂等）

2. 资源命名规范

# ✅ 好的设计
GET /users
GET /users/123
POST /users
GET /users/123/orders

# ❌ 避免这样
GET /getUsers
POST /createUser
GET /user?id=123

3. 使用复数名词

资源集合用复数：/users、/articles、/comments

4. 合理的状态码

• 200 OK - 成功
• 201 Created - 创建成功
• 204 No Content - 成功但无返回内容
• 400 Bad Request - 请求错误
• 401 Unauthorized - 未认证
• 403 Forbidden - 无权限
• 404 Not Found - 资源不存在
• 429 Too Many Requests - 请求过多
• 500 Internal Server Error - 服务器错误

5. 版本控制

# URL 路径版本
GET /api/v1/users
GET /api/v2/users

# 或 Header 版本
Accept: application/vnd.api+json; version=1

6. 统一的响应格式

{
  "code": 0,
  "message": "success",
  "data": { ... },
  "timestamp": 1234567890
}

遵循这些原则，你的 API 会更易理解、更易维护！