RESTful API 设计规范

核心原则

RESTful API 设计遵循资源导向和 HTTP 语义。

URL 设计规范

使用名词，不用动词

✅ /users ❌ /getUsers

使用复数形式

✅ /articles ❌ /article

嵌套资源表达关系

/users/123/articles

HTTP 方法语义

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

状态码使用

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

响应格式规范

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "example"
  }
}

版本控制

使用 URL 路径：/api/v1/users

总结

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