Node.js / 系统课时
编写自定义中间件
编写自定义中间件
自定义中间件适合把日志、耗时统计和请求预处理从具体路由里抽出来。本课用一个可运行的 Express 示例说明 req、res、next 如何串成执行链,并通过注册顺序控制解析、修改和响应的先后关系。
学习目标
- 解释普通中间件为什么必须调用
next()或主动结束响应。 - 实现请求日志、耗时统计和 JSON 字段预处理。
- 根据依赖关系安排
app.use()与路由的注册顺序。
中间件按注册顺序执行
Express 会按注册顺序检查中间件和路由。普通中间件拿到 req、res、next 后,要么调用 next() 把控制权交给后续处理器,要么用 res.send()、res.json() 等结束本次请求;两件事都不做,请求就会一直挂起。
一个常见 API 请求可以按下面的顺序注册:先记录开始时间,再用 express.json() 解析 JSON,请求预处理随后修改已解析的 req.body,最后进入业务路由。404 处理器放在所有业务路由之后,只接住前面都没有响应的请求。

实现日志、计时和请求预处理
下面示例使用 CommonJS,所用 API 兼容 Express 4.18+ 与 5.x。项目已安装 express 时,把代码保存为 server.js。日志中间件先注册,因此所有后续 API 都能计时;预处理中间件挂在 /api/users,只对该资源生效。
const express = require('express');
const { performance } = require('node:perf_hooks');
const app = express();
app.use((req, res, next) => {
// 进入请求链时记录起点,等响应完成后再计算总耗时。
const startedAt = performance.now();
res.on('finish', () => {
const durationMs = (performance.now() - startedAt).toFixed(1);
console.log(
`${req.method} ${req.originalUrl} ${res.statusCode} ${durationMs}ms`
);
});
next();
});
// 后续预处理依赖 req.body,因此 JSON 解析必须先注册。
app.use(express.json());
app.use('/api/users', (req, res, next) => {
// 只预处理本资源的 POST 请求,避免无条件修改所有请求。
if (req.method === 'POST' && typeof req.body?.name === 'string') {
req.body.name = req.body.name.trim();
}
next();
});
app.post('/api/users', (req, res) => {
if (!req.body?.name) {
return res.status(400).json({ error: 'name is required' });
}
res.status(201).json({ name: req.body.name });
});
app.use((req, res) => {
// 只有前面的中间件和路由都未结束请求时才会到这里。
res.status(404).json({ error: 'not found' });
});
app.listen(3000, () => {
console.log('listening on 3000');
});预期结果:运行 node server.js 后,再执行 curl -s -X POST http://localhost:3000/api/users -H "Content-Type: application/json" -d "{\"name\":\" Ada \"}"。响应中的姓名已去掉首尾空格,服务端日志中的 <TIME> 为实际动态耗时。
响应: {"name":"Ada"}
服务端日志: POST /api/users 201 <TIME>ms这里用 res.on('finish') 统计最终状态码和服务端处理耗时,比在 next() 之前直接打印结束时间更可靠,因为后者只能测到“进入下一个处理器之前”的时间。
顺序错误会发生什么
中间件的依赖关系应直接反映在注册顺序里。请求预处理需要读取 req.body,所以必须放在 express.json() 之后;全局日志要覆盖业务路由,就应放在这些路由之前。
| 错误顺序 | 直接后果 | 修正 |
|---|---|---|
预处理器在 express.json() 前 |
JSON 请求的 req.body 还未解析,name 无法被规范化 |
先 app.use(express.json()),再注册预处理器 |
| 日志中间件放在已结束响应的路由后 | 命中的路由不会再走到日志中间件 | 把日志中间件移到业务路由前 |
中间件既不响应也不调用 next() |
客户端持续等待,直到超时 | 明确选择“结束响应”或“继续链路” |
已发送响应后继续 next() |
后续处理器可能再次写响应 | 发送响应后直接 return |
排查执行顺序时,可以临时在每个关键中间件里打印固定标记,例如 A、B、C。一次请求只看这些标记的先后,就能确认实际链路是否和代码注册顺序一致。
给自定义中间件划清边界
日志、计时、请求 ID、鉴权前置检查、字段规范化都适合中间件,因为它们会被多个路由复用。业务动作本身不要塞进全局中间件,例如“创建用户”“扣减库存”应留在明确的路由或服务层,否则一次 app.use() 就可能意外影响大量路径。
请求预处理也要限定修改范围。本例只修剪 /api/users 的 POST name 字段;如果还要校验长度,可以在业务路由中要求 name.length 处于例如 1~80 之间,并对失败请求返回 400。这样中间件负责通用预处理,路由负责业务规则,两者的职责和失败位置都容易检查。