RESTful API 设计规范指南

1. 使用名词作为资源名

✅ 正确：

GET /users
GET /users/123
POST /users

❌ 错误：

GET /getUsers
POST /createUser

2. 使用 HTTP 方法表达操作

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

3. 使用复数名词

/users 而不是 /user
/articles 而不是 /article

4. 资源嵌套要有度

✅ 合理：

GET /users/123/articles

❌ 过度嵌套：

GET /users/123/articles/456/comments/789/replies

5. 使用查询参数过滤、排序、分页

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

6. 统一响应格式

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

7. 合理使用状态码

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

8. 版本控制

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

总结

遵循 RESTful 规范可以让 API 更直观、易维护、易扩展。