三、RESTful API 设计规范
REST（Representational State Transfer，表述性状态转移）是目前最主流的 API 设计风格。
3.1 RESTful 核心原则
3.2 RESTful API 设计示例
# 用户资源
# 获取用户列表
GET /api/v1/users?page=1&limit=20
# 获取单个用户
GET /api/v1/users/123
# 创建用户
POST /api/v1/users
Content-Type: application/json
{
"username": "zhangsan",
"email": "zs@example.com"
}
# 完整更新用户
PUT /api/v1/users/123
{
"username": "zhangsan_new",
"email": "zs_new@example.com"
}
# 部分更新用户
PATCH /api/v1/users/123
{
"email": "newemail@example.com"
}
# 删除用户
DELETE /api/v1/users/123
# 获取用户的订单列表（子资源）
GET /api/v1/users/123/orders
# 创建用户的订单
POST /api/v1/users/123/orders
{
"productId": 456,
"quantity": 2
}
3.3 统一的响应格式
在实际项目中，通常会定义统一的响应结构：
// 成功响应
{
"code": 200,
"message": "success",
"data": {
// 实际数据
},
"timestamp": 1705305600000
}
// 列表响应（带分页）
{
"code": 200,
"message": "success",
"data": {
"items": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 100,
"pages": 5
}
}
}
// 错误响应
{
"code": 400,
"message": "用户名已存在",
"errors": [
{
"field": "username",
"message": "用户名已被注册"
}
],
"timestamp": 1705305600000
}
3.4 命名规范
// ✅ 好的命名
GET /api/v1/users // 用户列表
GET /api/v1/users/123 // 单个用户
POST /api/v1/users // 创建用户
PUT /api/v1/users/123 // 更新用户
// ✅ 状态/动作可以用 query 参数
GET /api/v1/orders?status=paid
// ✅ 特殊操作可以用冒号表示
POST /api/v1/orders/123:cancel // 取消订单
POST /api/v1/users/123:activate // 激活用户
// ❌ 不好的命名
GET /api/v1/getAllUsers
GET /api/v1/getUserById?id=123
POST /api/v1/insertUser
POST /api/v1/user/create
