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 方法、处理结果和状态码。客户端先定位资源,再由方法决定操作;服务端完成校验和处理后,用状态码告诉客户端结果类别。

RESTful 用户资源路由映射图

常用错误状态码应保持稳定:请求体缺少必要字段返回 400 Bad Request,指定 ID 不存在返回 404 Not Found。不要把所有失败都返回 200,否则客户端只能解析消息文本判断结果。

在 Express 中实现路由

下面示例使用内存数组保存数据,便于聚焦路由设计。将代码保存为 app.js,先执行 npm init -y 和 npm install express,再运行应用。

js
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");
});

预期输出

text
API running at http://localhost:3000

端口 3000 是示例值,实际项目可通过环境变量配置为 <PORT>。

验证接口行为

另开一个终端创建用户。-i 会同时显示响应头,便于确认状态码和 Location 头。

bash
curl -i -X POST http://localhost:3000/users   -H "Content-Type: application/json"   -d '{"name":"Grace","email":"grace@example.com"}'

预期结果(关键响应)

text
HTTP/1.1 201 Created
Location: /users/3
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Grace","email":"grace@example.com"}

随后删除该用户。

bash
curl -i -X DELETE http://localhost:3000/users/3

预期结果(关键响应)

text
HTTP/1.1 204 No Content

响应头中的日期、连接信息和内容长度可能因环境不同而变化,验证时重点检查状态码、Location 和响应体。

关键边界

列表为空时仍应返回 200 和空数组,而不是 404。创建成功后返回 201,并可通过 Location 指向新资源。删除成功使用 204 时不能再返回 JSON 正文,否则语义相互冲突。

路由命名应保持一致,例如全部使用复数资源名和小写路径。筛选、排序、分页通常放在查询参数中,如 /users?page=2&status=active,不要为每个筛选条件创建新路径。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计 RESTful 路由

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通