RESTful API 设计指南

核心原则

资源导向

URL 应该表示资源，而非操作：

• ✅ /users/123
• ❌ /getUser?id=123

使用 HTTP 方法

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

URL 设计规范

GET    /articles          # 获取文章列表
GET    /articles/123      # 获取单篇文章
POST   /articles          # 创建文章
PUT    /articles/123      # 更新文章
DELETE /articles/123      # 删除文章
GET    /articles/123/comments  # 获取文章评论

状态码使用

• 200: 成功
• 201: 创建成功
• 204: 成功但无返回内容
• 400: 请求参数错误
• 401: 未授权
• 403: 禁止访问
• 404: 资源不存在
• 429: 请求过多
• 500: 服务器错误

响应格式

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "title": "文章标题"
  }
}

版本控制

• URL 路径：/api/v1/users
• 请求头：Accept: application/vnd.api.v1+json

分页与过滤

GET /articles?page=1&limit=20&sort=-created_at
GET /articles?status=published&category=tech

安全考虑

1. 使用 HTTPS
2. 身份验证（JWT/OAuth2）
3. 速率限制
4. 输入验证
5. CORS 配置

文档化

使用 Swagger/OpenAPI 自动生成文档。

总结

良好的 API 设计能提升开发者体验和系统可维护性。