RESTful API 设计最佳实践指南

资源命名规范

• 使用名词复数：/users, /articles
• 小写字母，连字符分隔：/user-profiles
• 避免动词：用 HTTP 方法表达操作

HTTP 方法语义

状态码正确使用

• 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

过滤、排序、分页

GET /users?role=admin&sort=created_at&limit=20&offset=0

响应格式统一

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

遵循这些实践，让你的 API 更加规范、易用、可维护。