RESTful API 设计指南：从入门到精通

核心原则

1. 资源导向

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

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

✅ POST   /users
❌ POST   /createUser

✅ DELETE /users/123
❌ POST   /deleteUser?id=123

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    # 资源冲突

500 Internal Server Error # 服务器错误

最佳实践

版本控制

# URL 版本 (推荐)
/api/v1/users

# Header 版本
Accept: application/vnd.api.v1+json

分页

GET /users?page=2&limit=20

# 响应
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

过滤和排序

GET /users?status=active&sort=-created_at

错误响应格式

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "邮箱格式不正确",
    "field": "email",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

总结

好的 API 设计应该直观、一致、易于使用。遵循 RESTful 原则可以让你的 API 更加专业和可维护。