RESTful API 设计最佳实践

核心原则

REST (Representational State Transfer) 是一种架构风格，遵循以下原则：

1. 资源导向: 一切皆资源
2. 统一接口: 使用标准 HTTP 方法
3. 无状态: 每个请求独立
4. 可缓存: 响应可缓存提升性能

HTTP 方法语义

方法	用途	幂等
GET	获取资源	是
POST	创建资源	否
PUT	更新资源 (全量)	是
PATCH	更新资源 (部分)	是
DELETE	删除资源	是

URL 设计规范

✅ 推荐:

GET /users
GET /users/123
POST /users
PUT /users/123
DELETE /users/123
GET /users/123/orders

❌ 避免:

GET /getUsers
POST /createUser
GET /user?id=123

状态码使用

• 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: 服务器错误

响应格式

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

版本控制

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

分页与过滤

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

安全考虑

1. 始终使用 HTTPS
2. 实现认证授权 (JWT/OAuth2)
3. 输入验证和 sanitization
4. 速率限制
5. CORS 配置

好的 API 设计让集成变得简单愉快！