React / 系统课时
设计 RESTful 路由
设计 RESTful 路由
本课把“用户管理”整理成一组可预测的 RESTful 接口:用资源名表达访问对象,用 HTTP 方法表达操作,并通过状态码区分成功、参数错误、资源不存在和删除完成。
学习目标
- 能按资源设计查询、创建、更新和删除路由
- 能为常见处理结果选择合适的 HTTP 状态码
- 能在 Express 中实现并验证一组完整接口
从资源而不是动作出发
RESTful 路由围绕资源建模。用户资源使用复数名词 /users,单个用户使用 /users/:id。路径描述“访问什么”,HTTP 方法描述“执行什么”,因此不再使用 /getUsers、/createUser 这类动词路径。
| 需求 | 方法与路径 | 典型成功状态码 |
|---|---|---|
| 查询用户列表 | GET /users |
200 OK |
| 查询单个用户 | GET /users/:id |
200 OK |
| 创建用户 | POST /users |
201 Created |
| 更新用户 | PATCH /users/:id |
200 OK |
| 删除用户 | DELETE /users/:id |
204 No Content |
PUT 通常表示整体替换资源,PATCH 表示局部修改。示例只更新传入字段,因此选择 PATCH 更准确。
请求与响应如何对应
一次请求需要同时考虑资源路径、HTTP 方法、处理结果和状态码。客户端先定位资源,再由方法决定操作;服务端完成校验和处理后,用状态码告诉客户端结果类别。

常用错误状态码应保持稳定:请求体缺少必要字段返回 400 Bad Request,指定 ID 不存在返回 404 Not Found。不要把所有失败都返回 200,否则客户端只能解析消息文本判断结果。
在 Express 中实现路由
下面示例使用内存数组保存数据,便于聚焦路由设计。将代码保存为 app.js,先执行 npm init -y 和 npm install express,再运行应用。
const express = require("express");
const app = express();
// 先解析 JSON,否则 req.body 会是 undefined
app.use(express.json());
// 使用内存数据聚焦路由语义,重启进程后数据会重置
let nextId = 3;
const users = [
{ id: 1, name: "Ada", email: "ada@example.com" },
{ id: 2, name: "Linus", email: "linus@example.com" }
];
app.get("/users", (req, res) => {
res.status(200).json(users);
});
app.get("/users/:id", (req, res) => {
const user = users.find((item) => item.id === Number(req.params.id));
// 单个资源不存在时返回 404,而不是空对象
if (!user) {
return res.status(404).json({ message: "User not found" });
}
res.status(200).json(user);
});
app.post("/users", (req, res) => {
const { name, email } = req.body;
if (!name || !email) {
return res.status(400).json({ message: "name and email are required" });
}
const user = { id: nextId++, name, email };
users.push(user);
res.status(201).location(`/users/${user.id}`).json(user);
});
app.patch("/users/:id", (req, res) => {
const user = users.find((item) => item.id === Number(req.params.id));
if (!user) {
return res.status(404).json({ message: "User not found" });
}
const { name, email } = req.body;
// PATCH 只修改请求中实际出现的字段
if (name !== undefined) user.name = name;
if (email !== undefined) user.email = email;
res.status(200).json(user);
});
app.delete("/users/:id", (req, res) => {
const index = users.findIndex((item) => item.id === Number(req.params.id));
if (index === -1) {
return res.status(404).json({ message: "User not found" });
}
users.splice(index, 1);
// 204 响应不能再携带 JSON 正文
res.status(204).send();
});
app.listen(3000, () => {
console.log("API running at http://localhost:3000");
});预期输出
API running at http://localhost:3000端口 3000 是示例值,实际项目可通过环境变量配置为 <PORT>。
验证接口行为
另开一个终端创建用户。-i 会同时显示响应头,便于确认状态码和 Location 头。
curl -i -X POST http://localhost:3000/users -H "Content-Type: application/json" -d '{"name":"Grace","email":"grace@example.com"}'预期结果(关键响应)
HTTP/1.1 201 Created
Location: /users/3
Content-Type: application/json; charset=utf-8
{"id":3,"name":"Grace","email":"grace@example.com"}随后删除该用户。
curl -i -X DELETE http://localhost:3000/users/3预期结果(关键响应)
HTTP/1.1 204 No Content响应头中的日期、连接信息和内容长度可能因环境不同而变化,验证时重点检查状态码、Location 和响应体。
关键边界
列表为空时仍应返回 200 和空数组,而不是 404。创建成功后返回 201,并可通过 Location 指向新资源。删除成功使用 204 时不能再返回 JSON 正文,否则语义相互冲突。
路由命名应保持一致,例如全部使用复数资源名和小写路径。筛选、排序、分页通常放在查询参数中,如 /users?page=2&status=active,不要为每个筛选条件创建新路径。