RESTful API 设计原则

什么是 REST？

REST (Representational State Transfer) 是一种架构风格，强调资源的统一接口和无状态通信。

核心原则

1. 资源导向

用名词表示资源，不用动词:

• ✅ /users
• ❌ /getUsers

2. 使用 HTTP 方法

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

3. 状态码规范

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

URL 设计最佳实践

# 获取用户列表
GET /users

# 获取单个用户
GET /users/123

# 创建用户
POST /users

# 更新用户
PUT /users/123

# 获取用户订单
GET /users/123/orders

版本控制

在 URL 中包含版本号:

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

响应格式

统一使用 JSON:

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

遵循这些原则，让你的 API 更规范、更易用！