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,并用内存数组代替数据库,便于把注意力放在资源路径、方法和状态码上。
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');
});预期输出:
REST server listening at http://127.0.0.1:3000保持服务器运行,在另一个终端验证查询与创建:
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。这样路由、权限、日志与接口文档都能围绕同一资源组织。