浏览器发出的请求只是一个方法、一条路径、若干请求头,有时再加上请求体。本单元说明 Express 程序如何把这样的请求变成决定:哪个处理函数运行、JSON 请求体如何成为 req.body,以及响应由哪个状态码、响应头和响应体组成。代码是教学示例,并非已安装或部署的服务。
1. 从请求到处理函数
定义 8.1.1
(路由与处理函数)
路由把一个 HTTP 方法和一个路径模式与一个处理函数配对,处理函数即 (req, res) 或 (req, res, next) 形式的函数。Express 按注册顺序,把每个请求与已注册的路由和中间件匹配。发送了响应的处理函数会结束搜索;调用 next() 的处理函数则把请求交给下一个匹配项。
每个 HTTP 请求都携带方法(如 GET、POST 或 PATCH)和目标(路径,后面可带查询字符串)。Express 按注册顺序将每个请求与路由比较。只有方法和路径模式都符合,路由才匹配:
| 请求 | app.get('/items/:id') | app.patch('/items/:id') |
|---|---|---|
GET /items/1 | 匹配 | 不匹配(方法错误) |
PATCH /items/1 | 不匹配(方法错误) | 匹配 |
GET /items | 不匹配(路径缺少 id 片段) | 不匹配 |
方法表达要做什么;路径标识哪个资源。
2. 路径参数与查询字符串
路径参数可标识特定资源。在 /items/:id 中,请求 /items/42 给出 req.params.id === '42'。这个单路径片段的 :id 参数是字符串,因此以字符串为键的 Map 可避免数字与字符串不匹配。不要把这一点推广到所有 Express 5 参数:通配符参数可能包含路径片段数组。
查询字符串可细化或过滤集合:在 /items?q=note 中,Express 提供 req.query.q。查询字符串不参与路由匹配,因此 /items 与 /items?q=note 到达同一个处理函数。重复键如 ?q=a&q=b 可能产生数组。使用前检查 typeof req.query.q === 'string'。
一个实用规则:如果去掉该值后指向的是另一个资源,用路径;如果它只缩小列表范围,用查询字符串。
反例模式
数字键永远匹配不到路径参数
有人声称:存储结构可以用数字作键,因为请求 GET /items/1 选的是项目 1。假设存储结构是 new Map([[1, { id: 1, name: 'Sample item' }]]),而处理函数执行 items.get(req.params.id)。对于 GET /items/1,req.params.id 是字符串 '1'。Map 以 same-value-zero 规则比较键,不会把 '1' 与 1 视为相等,所以 items.get('1') 返回 undefined,处理函数便响应 404,尽管项目其实存在。应像完整示例那样保持键为字符串;或者先确认参数是规范的整数字符串,再有意识地转换一次。
3. JSON 请求体、Content-Type 与中间件顺序
浏览器在请求体中发送 JSON,并以 Content-Type: application/json 标识。Express 不会自动读取请求体。express.json() 中间件读取并解析请求体,但仅当请求的 Content-Type 符合其 type 选项时才处理;该选项默认为 application/json。
需要区分三种情况:
- 类型匹配,JSON 被接受。
req.body保存解析后的值。默认strict: true接受对象和数组;下方路由之后会实施更严格的对象和字段验证。 - 类型匹配,JSON 格式错误或不被允许。 解析器跳过普通路由处理函数并转发错误:状态为
400,类型为'entity.parse.failed'。即使语法有效,标量 JSON(如42或null)也会被strict: true拒绝。 - 类型不匹配或缺失。 若此前没有其他请求体解析器,
req.body保持undefined。这不是解析错误。下方 POST 和 PATCH 处理函数若被执行且类型检查失败,会选择返回415 Unsupported Media Type。
顺序很重要。app.use(express.json()) 必须在读取 req.body 的路由之前注册。错误处理中间件接受四个参数 (err, req, res, next),并在路由之后注册。
常见错误
(太早注册后备处理函数或解析器)
注册顺序就是匹配顺序。放在路由之前的通配 app.use((req, res) => res.status(404).json(...)) 会使每个请求都得到 404,包括 GET /items/1,因为它最先匹配并发送响应。放在路由之后的解析器,则会使那些路由中的 req.body 为 undefined。正确顺序是:先注册解析器,然后是路由,接着是 404 后备处理函数,最后才是错误中间件。
4. 验证、return 与 next
一个请求最多应收到一个最终响应。处理函数必须完成响应或继续传递控制权。return res.status(400).json(...) 发送响应并停止该函数,因此后续语句不会尝试再发送第二次响应。
调用 next() 则不同:它把控制权交给下一个匹配的路由或中间件。调用 next(err) 会跳过普通中间件并进入错误处理函数。由当前函数回答时使用 return res...;希望另一层处理时使用 next(err)。
安全地验证属性是否存在。body.name !== undefined 会漏掉属性存在但值为 undefined 的情况,而 'name' in body 也会找到继承的原型属性。Object.hasOwn(body, 'name') 和 Object.keys(body) 只考虑对象自身的属性。另外先确认请求体是普通对象。JSON 数组可以成功解析,但在这里不是有效输入。
常见错误
(真值检查不是验证)
if (!body.name) return res.status(400)... 这类检查会拒绝缺少的名称和空字符串,却接受任何真值。对于请求体 {"name":42} 或 {"name":["a"]},该值是真值,检查通过,之后调用 body.name.trim() 便抛出 TypeError,因为数字和数组都没有 trim 方法。Express 于是响应 500,把本属客户端的错误当作服务器故障。应像 isValidName 那样明确检查类型与范围,使这类输入得到 400。
5. 状态、响应头与响应体
响应有三部分:
- 状态码,例如
200或404; - 响应头,例如
Content-Type和Location; - 响应体,此处为 JSON。
res.status(code) 设置状态码。res.location(url) 设置 Location。res.json(value) 序列化该值,设置 Content-Type: application/json; charset=utf-8 并发送响应。
6. 完整示例
这是说明用途的 Express 5 CommonJS 程序,需要 Node.js 18 或更高版本。本章未安装或运行它。路由处理函数中写出的响应是教学用的设计选择;解析器失败则遵循 Express/body-parser 的行为。
'use strict';
const express = require('express');
const app = express();
app.disable('x-powered-by');
app.set('etag', false);
// In-memory store: one process only, reset on every restart.
const items = new Map([['1', { id: '1', name: 'Sample item' }]]);
let nextId = 2; // classroom counter; assumed to stay within the safe integer range
function isPlainObject(value) {
return typeof value === 'object' && value !== null
&& Object.getPrototypeOf(value) === Object.prototype;
}
function isValidName(value) {
return typeof value === 'string'
&& value.trim().length > 0
&& value.trim().length <= 100;
}
app.use(express.json());
// GET collection, optional ?q= filter -> 200
app.get('/items', (req, res) => {
const q = typeof req.query.q === 'string' ? req.query.q.toLowerCase() : '';
const list = [...items.values()].filter((item) =>
item.name.toLowerCase().includes(q));
res.status(200).json(list);
});
// GET one -> 200 or 404
app.get('/items/:id', (req, res) => {
const item = items.get(req.params.id);
if (!item) {
return res.status(404).json({ error: 'Item not found' });
}
res.status(200).json(item);
});
// POST create -> 201, 400 or 415
app.post('/items', (req, res) => {
if (!req.is('application/json')) {
return res.status(415).json({ error: 'Content-Type must be application/json' });
}
const body = req.body;
if (!isPlainObject(body) || !Object.hasOwn(body, 'name') || !isValidName(body.name)) {
return res.status(400).json({ error: 'name must be a non-empty string (max 100)' });
}
const id = String(nextId++);
const item = { id, name: body.name.trim() };
items.set(id, item);
res.status(201).location(`/items/${id}`).json(item);
});
// PATCH update -> 200, 400, 404 or 415
app.patch('/items/:id', (req, res) => {
const item = items.get(req.params.id);
if (!item) {
return res.status(404).json({ error: 'Item not found' });
}
if (!req.is('application/json')) {
return res.status(415).json({ error: 'Content-Type must be application/json' });
}
const body = req.body;
if (!isPlainObject(body)) {
return res.status(400).json({ error: 'Body must be a JSON object' });
}
const keys = Object.keys(body);
if (keys.length !== 1 || keys[0] !== 'name') {
return res.status(400).json({ error: 'Only the name field may be updated' });
}
if (!isValidName(body.name)) {
return res.status(400).json({ error: 'name must be a non-empty string (max 100)' });
}
item.name = body.name.trim();
res.status(200).json(item);
});
// Unmatched method/path -> 404
app.use((req, res) => {
res.status(404).json({ error: 'Route not found' });
});
// Error middleware: malformed/disallowed JSON; other errors are delegated
app.use((err, req, res, next) => {
if (err.type === 'entity.parse.failed') {
return res.status(400).json({ error: 'Invalid JSON body: expected an object or array' });
}
next(err);
});
app.listen(3000);
示例的设计说明:
req.is()同时检查内容类型和 HTTP 请求体分帧;它不验证 JSON 或必需字段。不要仅凭没有载荷字节推断响应。例如,有分帧的空 JSON 请求体可能进入字段验证并收到400。- 全局 JSON 解析器在所有路由前运行。因此,即使请求为
PATCH /items/99,格式错误的 JSON 也会产生400,根本不会执行 id 检查。解析成功或被跳过后,PATCH 处理函数先检查资源是否存在,所以未知 id 会在内容检查前收到404。 - 其他解析器错误会继续交由后续处理:请求体过大收到
413,不支持的字符集或内容编码收到415。Express 默认处理函数使用错误的4xx或5xx状态,否则使用500。其响应体不是本应用的 JSON 错误格式。
7. 例题详解
例题 8.1.2
(创建项目并读回)
以下追踪由手工构造,而非从运行中的服务器捕获。它示意客户端请求与预期响应。Date 的值会变化,Node.js 连接头(Connection、Keep-Alive)已省略。内容长度计算 UTF-8 载荷字节,不包括显示响应体时可能附加的换行。
POST /items HTTP/1.1
Host: localhost:3000
Content-Type: application/json
Content-Length: 19
{"name":"Notebook"}
HTTP/1.1 201 Created
Location: /items/2
Content-Type: application/json; charset=utf-8
Content-Length: 28
Date: <varies>
{"id":"2","name":"Notebook"}
沿着请求走过整个程序。express.json() 看到 Content-Type: application/json,读取 19 个字节的请求体,并把 req.body 设为 { name: "Notebook" }。路由器因方法不同而跳过两条 GET 路由,进入 POST /items 处理函数。在那里,req.is('application/json') 为真值,请求体是带有自身 name 属性的普通对象,isValidName 接受该字符串。处理函数取得 id '2',把 nextId 增至 3,保存项目,并以 201、Location 响应头和 JSON 响应体作答。读回状态即可确认变更:GET /items/2 以 200 返回同一个对象,而 GET /items?q=note 返回只含该项目的数组,因为 'sample item' 不含 note,'notebook' 则含有。
例题 8.1.3
(每个请求由哪一层响应)
以下汇总假设示例 POST 已创建项目 2。除特别说明外,带请求体的请求使用 Content-Type: application/json,并采用解析器大小限制以内的普通 UTF-8 编码:
| 请求 | 结果 |
|---|---|
GET /items/1 | 200,带示例项目 |
GET /items/99 | 404 {"error":"Item not found"} |
POST /items,请求体 {"name":" "} | 400 |
POST /items,请求体 {"name": | 400,带上面的 JSON 解析器错误消息 |
POST /items,请求体 42 | 400,因为严格 JSON 解析拒绝标量 |
POST /items,Content-Type: text/plain | 415 |
PATCH /items/2,请求体 {"name":"Diary"} | 200 |
PATCH /items/2,请求体 {"color":"red"} | 400 |
PATCH /items/99 | 404 |
PATCH /items/99,JSON 格式错误 | id 检查前返回 400 |
按产生响应的层次把各行分组。在任何路由执行之前,错误中间件响应解析器拒绝的两种请求体:被截断的 {"name": 和被 strict 拒绝的标量 42。其余由路由处理函数响应:未知 id 得 404,req.is 失败得 415,空白名称或多余字段等验证失败则得 400。对 PATCH /items/99,id 检查先于请求体检查,所以格式正确的请求体仍得 404;格式错误的 JSON 根本到不了处理函数,得 400。因此,这个表格记录的不只是一串状态码,还有各项检查的顺序。
例题 8.1.4
(太晚注册解析器)
假设把程序中的两行注册对调,使路由排在前面。
// Faulty order: the routes are registered before the parser.
app.post('/items', createItem); // the same handler as in the full example
app.use(express.json());
客户端发送与第一个例题相同的成功请求:POST /items,Content-Type: application/json,请求体为 {"name":"Notebook"}。路由器在解析器运行之前就到达 POST /items 处理函数,所以 req.body 仍是 undefined。处理函数中的 req.is('application/json') 只检查请求头,所以会通过,不会得 415。接着 isPlainObject(undefined) 为假,处理函数响应 400 {"error":"name must be a non-empty string (max 100)"}。同一个输入现在失败了,而消息把责任推给输入,其实问题在注册顺序。格式错误的请求体也只会得到这个笼统的 400,而不是解析器的错误响应。修正方法是把 app.use(express.json()) 注册在每一条读取 req.body 的路由之前。
8. 客户端:Promise、response.ok 与 DOM
fetch 在浏览器中返回一个 Promise。收到响应头时它会兑现,即使状态为 404 或 500 也是如此。请求失败,包括网络错误、无效请求和取消,可能使其拒绝。在把响应视为成功之前,检查 response.ok;状态为 200–299 时它为真。
async function createItem(name) {
const response = await fetch('/items', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name }),
});
if (!response.ok) {
throw new Error(`Create failed with status ${response.status}`);
}
return response.json(); // another Promise: the parsed body
}
response.json() 异步读取并解析响应体,它本身也可能拒绝,例如服务器返回无效 JSON 时。createItem 的调用者必须处理两个阶段的失败。
服务器的 Map 与页面的 DOM 是不同程序中的独立状态。成功的 POST 改变 Map,但页面只有在客户端代码随后更新 DOM 时才会改变。仅编辑 DOM 不会改变服务器;事件处理函数需要另发请求。
两个请求不一定按浏览器启动它们的顺序完成。如果对每个响应都更新 DOM,却不检查哪个操作仍是当前操作,就可能显示过期数据。本例中每次服务器变更是同步的,但竞争的 PATCH 请求仍按服务器处理顺序覆盖同一个名称。这里没有版本检查,重试 POST 也可能创建第二个项目。可靠的冲突处理与重试去重需要明确设计。
重启 Node 进程会重新创建只含一个示例项目的 Map,并把 nextId 重置为 2。运行两个进程会得到两个独立的 Map。要跨进程保留并协调这一状态,需要持久的共享存储(常见选择是数据库)和适当的并发控制。
9. 练习
快速检查
(由哪个处理函数响应?)
对完整示例,说明下列请求的响应:(a) DELETE /items/1、(b) POST /items/1、(c) GET /items?q=a&q=b。
解答
(a) 没有任何路由注册 DELETE,请求落到最后的处理函数:404 {"error":"Route not found"}。(b) POST 只为 /items 注册,所以 POST /items/1 同样到达最后的处理函数,得到相同的 404。较严谨的 API 可能响应 405 Method Not Allowed 并附上 Allow 响应头,但本程序不是这样。(c) 路由 GET /items 匹配。req.query.q 是数组,所以 typeof req.query.q === 'string' 为假,q 成为空字符串,以 200 返回所有项目。
快速检查
(选择状态码)
对 POST /items,给出状态码及产生它的层次:(a) JSON 请求体 {"name":42};(b) JSON 请求体 {"name":;(c) Content-Type: text/plain,请求体为 hello。
解答
(a) 路由处理函数响应 400:请求体能解析,但 isValidName 拒绝数字。(b) 错误中间件响应 400:解析器以 entity.parse.failed 失败,处理函数从未运行。(c) 路由处理函数响应 415:express.json() 跳过不匹配的类型,使 req.body 保持为 undefined,然后 req.is('application/json') 失败。
快速检查
(重复响应)
找出缺陷:app.get('/items/:id', (req, res) => { const item = items.get(req.params.id); if (!item) res.status(404).json({ error: 'Item not found' }); res.status(200).json(item); });
解答
404 分支没有 return,所以程序继续执行第二句 res.status(200).json(item)。客户端已收到 404,第二次尝试对已发出的响应设置响应头,使 Node 抛出 ERR_HTTP_HEADERS_SENT。修正方法是 return res.status(404).json({ error: 'Item not found' });,既发送响应,又结束函数。
快速检查
(有效输入却得 400)
重构之后,POST /items 带 Content-Type: application/json 和请求体 {"name":"Diary"} 返回 400,但处理函数的代码没有改动。最可能的原因是什么?如何确认?
解答
最可能的原因是 app.use(express.json()) 现在排在路由之后,或已被移除,所以处理函数运行时 req.body 是 undefined。isPlainObject(undefined) 为假,因而得 400。要确认,可在处理函数开头打印 req.body,或比对 app.use 与路由注册的顺序;修正方法是先注册解析器。
快速检查
(在浏览器中读取 404)
浏览器运行 const response = await fetch('/items/99');。这个 Promise 会怎样?response.ok 与 response.status 是什么?调用 response.json() 之前,代码必须检查什么?
解答
Promise 会兑现,因为响应头已到达;HTTP 失败状态不会使它被拒绝。response.status 是 404,response.ok 是 false。代码应先检查 response.ok,再把响应体当作项目。这里的响应体是 {"error":"Item not found"},response.json() 能顺利解析,所以若跳过检查,会默默把错误对象当作数据。