在 RESTful API 设计中，增删改查（CRUD）操作的返回信息应遵循 HTTP 状态码 和 数据格式 的最佳实践。以下是各操作的标准返回示例和规范：
1. 查询数据（GET）
返回所有数据（GET /resources）
参数说明
| 参数 | 类型 | 默认值 | 说明 |
|---|
page | integer | 1 | 当前页码 |
limit | integer | 10 | 每页数据条数 |
sort | string | id | 排序字段（可选） |
order | string | ASC | 排序方向（可选） |
{
"data": [
{ "id": 1, "name": "Alice", "email": "alice@example.com" },
{ "id": 2, "name": "Bob", "email": "bob@example.com" }
],
"meta": {
page,
limit,
total: totalResult.total, // 数据总数
total_pages: Math.ceil(totalResult.total / limit),
}
}
- 状态码：
200 OK
- 最佳实践：
- 分页时返回
meta 信息（如总数、页码）。
- 空数据返回
[] 而非 null。
返回单个数据（GET /resources/{id}）
{
"id": 1,
"name": "Alice",
"email": "alice@example.com"
}
2. 新增数据（POST）
成功创建（POST /resources）
{
"id": 3,
"name": "Charlie",
"email": "charlie@example.com",
"created_at": "2023-10-01T12:00:00Z"
}
- 状态码：
201 Created
- 最佳实践：
- 返回 完整创建的数据（包括生成的
id 和默认字段）。
- 在响应头中添加
Location 指向新资源：
Location: /resources/3
冲突时（如唯一键重复）
3. 修改数据（PUT/PATCH）
成功更新（PUT /resources/{id}）
{
"id": 1,
"name": "Alice Updated",
"email": "alice.new@example.com",
"updated_at": "2023-10-01T12:30:00Z"
}
- 状态码：
200 OK（或 204 No Content 如果无需返回数据）
- 最佳实践：
PUT（全量更新）返回 完整更新后的数据。PATCH（部分更新）可只返回更新的字段。
数据不存在时
4. 删除数据（DELETE）
成功删除（DELETE /resources/{id}）
- 状态码：
204 No Content（推荐）
（无响应体，表示成功但无返回数据）
或返回简单确认：
{ "message": "Resource deleted" }
数据不存在时
5. 错误处理通用规范
所有错误应包含 明确的错误信息 和 状态码：
{
"error": "Validation failed",
"details": [
{ "field": "email", "message": "Invalid email format" }
]
}
- 常见状态码：
400 Bad Request：参数错误。401 Unauthorized：未认证。403 Forbidden：无权限。500 Internal Server Error：服务器内部错误。
对比总结
| 操作 | 推荐状态码 | 返回数据内容 | 备注 |
|---|
| GET | 200 | 资源数据（单个或列表） | 空列表返回 [] |
| POST | 201 | 完整创建的资源 | 需包含 Location 头 |
| PUT | 200 | 完整更新后的资源 | 或 204（无内容） |
| PATCH | 200 | 更新后的字段（或完整资源） | |
| DELETE | 204 | 无内容 | 或 200 + 确认消息 |
基础概念
| 操作 | HTTP 方法 | 路径示例 | 描述 |
|---|
| 查询 | GET | /users | 获取所有用户 |
| 查询 | GET | /users/{id} | 获取单个用户 |
| 新增 | POST | /users | 创建用户 |
| 修改 | PUT/PATCH | /users/{id} | 全量更新（PUT）或部分更新（PATCH） |
| 删除 | DELETE | /users/{id} | 删除用户 |
实际示例（Cloudflare Worker + D1）
// 更新用户（PUT /users/{id}）
async function updateUser(db: D1Database, id: string, data: any) {
const { success } = await db
.prepare('UPDATE users SET name = ?, email = ? WHERE id = ?')
.bind(data.name, data.email, id)
.run();
if (!success) {
return new Response(
JSON.stringify({ error: "Update failed" }),
{ status: 500 }
);
}
// 返回更新后的数据
const user = await db
.prepare('SELECT * FROM users WHERE id = ?')
.bind(id)
.first();
return new Response(JSON.stringify(user), {
status: 200,
headers: { 'Content-Type': 'application/json' },
});
}
遵循这些规范可以确保你的 API 易用、一致且符合 REST 设计原则！
补充说明：
关键注意事项
- HTTP 状态码：
- 200 OK：成功查询或更新。
- 201 Created：资源创建成功。
- 204 No Content：删除成功或无返回内容。
- 404 Not Found：资源不存在。
- 幂等性：
- PUT 和 DELETE 是幂等的（多次请求效果相同）。
- POST 是非幂等的（每次请求可能产生新资源）。
- 数据验证：
- 始终验证请求体（如字段是否缺失、数据类型是否正确）。
- 数据库集成：
- 实际项目中替换模拟数据为数据库操作（如 MySQL、MongoDB）。