RESTful API 设计原则与实战指南

REST 核心原则

1. 资源导向

URL 应该表示资源，而不是动作：

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

❌ GET /getUsers
❌ POST /createUser

2. 使用正确的 HTTP 方法

• GET: 获取资源 (幂等)
• POST: 创建资源
• PUT: 完整更新资源 (幂等)
• PATCH: 部分更新资源
• DELETE: 删除资源 (幂等)

3. 合理的状态码

200 OK - 请求成功
201 Created - 资源创建成功
204 No Content - 成功但无返回内容
400 Bad Request - 请求参数错误
401 Unauthorized - 未授权
403 Forbidden - 禁止访问
404 Not Found - 资源不存在
409 Conflict - 资源冲突
422 Unprocessable Entity - 参数验证失败
429 Too Many Requests - 请求过多
500 Internal Server Error - 服务器错误

4. 版本控制

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

或在 Header 中指定版本。

5. 过滤、排序、分页

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

6. 统一的响应格式

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

错误响应：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "参数验证失败",
    "details": [...]
  }
}

安全最佳实践

1. 始终使用 HTTPS
2. 认证授权: JWT、OAuth2
3. 输入验证: 防止 SQL 注入、XSS
4. 速率限制: 防止滥用
5. 敏感信息: 不在 URL 中传递密码、token
6. CORS: 正确配置跨域策略

文档化

使用 OpenAPI/Swagger 自动生成文档，保持文档与代码同步。

总结

好的 API 设计应该：直观、一致、安全、易文档化。站在调用者的角度思考设计。