RESTful API 设计规范

什么是 RESTful？

REST 是一种架构风格，强调资源、无状态和统一接口。

核心原则

1. 资源导向

GET    /users          # 获取用户列表
GET    /users/123      # 获取用户 123
POST   /users          # 创建用户
PUT    /users/123      # 更新用户 123
DELETE /users/123      # 删除用户 123

2. 使用 HTTP 方法

• GET: 查询
• POST: 创建
• PUT: 全量更新
• PATCH: 部分更新
• DELETE: 删除

3. 状态码规范

200 OK          // 成功
201 Created     // 创建成功
400 Bad Request // 请求错误
401 Unauthorized// 未授权
403 Forbidden   // 禁止访问
404 Not Found   // 资源不存在
500 Server Error// 服务器错误

URL 设计规范

使用名词，不用动词

❌ /getUsers ✅ /users

使用复数

✅ /users, /articles

嵌套资源

✅ /users/123/orders

查询参数

GET /users?page=1&limit=20&sort=created_at

响应格式

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

版本控制

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

安全考虑

• 使用 HTTPS
• 认证授权 (JWT/OAuth)
• 限流防刷
• 输入验证

总结

好的 API 设计让前后端协作更顺畅，文档清晰是关键。