Node.js / 系统课时

设计 RESTful 资源

设计 RESTful 资源

RESTful 资源设计要先把业务对象变成稳定的 URL,再用 HTTP 方法表达操作、用状态码表达结果。完成本节后,你可以为“用户”资源写出可直接实现的路径表,并在 Node.js 中跑通查询与创建两个最小接口。

学习目标

  • 根据业务对象设计集合资源与单个资源路径
  • 为常见增删改查选择合适的 HTTP 方法和状态码
  • 在 Node.js 中实现并验证一个最小 REST 接口

从业务对象确定资源路径

先找“可被独立标识的名词”,再决定集合与单个资源。以用户为例,集合使用 /users,单个用户使用 /users/:id。路径用名词而不是动作,/getUser/42、/createUser 会把操作写进 URL,后续方法与权限规则更难统一。

业务意图 推荐路径 说明
查询用户列表 GET /users 集合资源
查询用户 42 GET /users/42 单个资源
创建用户 POST /users 由服务器分配新 ID
替换用户 42 PUT /users/42 用完整表示替换资源
局部修改用户 42 PATCH /users/42 只提交需要修改的字段
删除用户 42 DELETE /users/42 删除指定资源

查询条件放在 query string,例如 GET /users?role=admin&limit=20。它仍然是在查询 /users 集合,而不是创建新的“admin 用户”资源。

用 HTTP 方法表达动作

方法选择要与重复请求的语义一致。GET 只读取数据;POST 常用于在集合下创建新资源;PUT 通常表示完整替换;PATCH 表示局部更新;DELETE 删除目标资源。设计时可用同一张资源表检查方法是否表达清楚,而不是继续发明 /users/42/update 这类动作路径。

创建资源后,推荐返回 201 Created,并在 Location 响应头给出新资源地址。例如创建 ID 为 43 的用户后,可返回 Location: /users/43。如果删除成功且没有响应体,可以返回 204 No Content。

用状态码表达处理结果

不要只依赖 JSON 里的 success 字段判断成功或失败,HTTP 状态码本身就是协议的一部分。下面这组状态码足以覆盖多数基础 CRUD 接口。

场景 状态码 适用条件
查询成功 200 返回资源或列表
创建成功 201 新资源已经创建
删除成功且无正文 204 响应体为空
请求字段非法 400 JSON 合法,但参数不符合要求
资源不存在 404 路径合法但目标 ID 不存在
唯一约束冲突 409 如邮箱已经被占用

例如 GET /users/999 查不到用户时,应直接返回 404;不要返回 200 再让客户端解析 { "success": false } 才知道失败。

在 Node.js 中落一个最小资源接口

下面示例适用于 Node.js 18+,只使用内置 node:http。它实现 GET /users/:id 与 POST /users,并用内存数组代替数据库,便于把注意力放在资源路径、方法和状态码上。

js
import http from 'node:http';

const users = [{ id: 42, name: 'Ada' }];

function sendJson(res, statusCode, body, headers = {}) {
  const payload = JSON.stringify(body);
  res.writeHead(statusCode, {
    'content-type': 'application/json; charset=utf-8',
    'content-length': Buffer.byteLength(payload),
    ...headers
  });
  res.end(payload);
}

const server = http.createServer((req, res) => {
  const url = new URL(req.url, 'http://localhost');
  const match = url.pathname.match(/^\/users\/(\d+)$/);

  if (req.method === 'GET' && match) {
    const id = Number(match[1]);
    const user = users.find((item) => item.id === id);
    return user
      ? sendJson(res, 200, user)
      : sendJson(res, 404, { error: 'USER_NOT_FOUND' });
  }

  if (req.method === 'POST' && url.pathname === '/users') {
    let raw = '';
    req.on('data', (chunk) => { raw += chunk; });
    req.on('end', () => {
      const input = JSON.parse(raw);
      const user = { id: users.at(-1).id + 1, name: input.name };
      users.push(user);
      sendJson(res, 201, user, { location: `/users/${user.id}` });
    });
    return;
  }

  sendJson(res, 404, { error: 'ROUTE_NOT_FOUND' });
});

server.listen(3000, '127.0.0.1', () => {
  console.log('REST server listening at http://127.0.0.1:3000');
});

预期输出:

text
REST server listening at http://127.0.0.1:3000

保持服务器运行,在另一个终端验证查询与创建:

bash
curl -i http://127.0.0.1:3000/users/42
curl -i -X POST http://127.0.0.1:3000/users -H "Content-Type: application/json" -d '{"name":"Grace"}'

预期结果分别包含 HTTP/1.1 200 OK 与用户 42,以及 HTTP/1.1 201 Created、Location: /users/43 和新建用户 JSON。Node.js 可能补充 Date、Connection 等响应头,具体值会随运行环境变化。

检查资源设计是否偏离 REST

交付接口前逐项检查:路径是否以名词为主;集合与单个资源是否可从 URL 看出层级;同一资源是否通过 HTTP 方法区分操作;成功与失败是否使用匹配的状态码;创建接口是否能告诉客户端新资源地址。

一个常见反例是同时存在 POST /createUser、POST /updateUser、POST /deleteUser。更一致的设计是 POST /users、PATCH /users/:id、DELETE /users/:id。这样路由、权限、日志与接口文档都能围绕同一资源组织。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计 RESTful 资源

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

登录哪都通