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,只对该资源生效。

js
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> 为实际动态耗时。

text
响应: {"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。这样中间件负责通用预处理,路由负责业务规则,两者的职责和失败位置都容易检查。

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

目录与阅读设置

阅读设置

17

记录一个想法

编写自定义中间件

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

登录哪都通