RESTful API 设计原则与实战

好的 API 设计让前后端协作更高效。遵循 REST 原则是关键。

核心原则

1. 资源导向

用名词表示资源，不用动词：

• ✅ GET /users - 获取用户列表
• ❌ GET /getUsers

2. 正确使用 HTTP 方法

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

3. 状态码规范

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

最佳实践

版本控制

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

分页

GET /users?page=1&limit=20

过滤排序

GET /users?status=active&sort=created_at&order=desc

响应格式

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

安全考虑

• 使用 HTTPS
• 实现认证（JWT/OAuth2）
• 限制请求频率
• 验证输入参数

好的 API 设计是长期投资，值得花时间打磨。