RESTful API 设计规范

核心原则

REST 是一种架构风格，强调资源导向和无状态通信。

URL 设计

使用名词表示资源

✅ GET /users
✅ GET /users/123
✅ POST /users
✅ PUT /users/123
✅ DELETE /users/123

避免动词

❌ GET /getUsers
❌ POST /createUser

HTTP 方法语义

• GET：获取资源
• POST：创建资源
• PUT：更新资源（全量）
• PATCH：更新资源（部分）
• DELETE：删除资源

状态码使用

200 OK - 成功
201 Created - 创建成功
204 No Content - 成功但无返回
400 Bad Request - 请求错误
401 Unauthorized - 未授权
403 Forbidden - 禁止访问
404 Not Found - 资源不存在
500 Internal Server Error - 服务器错误

版本控制

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

响应格式

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

分页与过滤

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

安全建议

1. 使用 HTTPS
2. 实现认证授权
3. 限制请求频率
4. 验证输入数据