Node.js 中间件的工作原理

你可能在 Express 代码库中见过到处都是 app.use()。你知道中间件位于请求和响应之间。但当这个链条中出现问题时——请求挂起、错误消失或处理程序以错误的顺序触发——这个心智模型就崩溃了。

本文将解释 Node.js 中间件的实际工作原理:它是什么、控制流如何在链中传递,以及 Express 5 中发生了哪些变化。

中间件是框架模式,而非 Node.js 特性

Node.js 本身没有中间件概念。核心 http 模块只给你提供请求和响应对象——仅此而已。中间件是 Express 等框架在 Node.js 之上实现的一种模式。

Express 中间件遵循特定的结构:接收 req、res 和 next 的函数。框架维护这些函数的堆栈,并为每个传入请求按顺序调用它们。这种 Node.js 框架中的请求生命周期赋予了中间件强大的能力。

其他框架以不同方式实现类似的模式。Koa 使用”洋葱模型”,其中中间件包裹后续处理程序。Fastify 在特定生命周期点使用钩子。概念可以迁移,但语义不同。

请求-响应生命周期

当请求到达 Express 应用程序时,它进入一个管道:

1. Express 将请求与已注册的中间件和路由进行匹配
2. 每个中间件函数按注册顺序执行
3. 控制通过 next() 向前传递,或在发送响应时停止
4. 错误处理中间件捕获传递给 next(err) 的错误,以及在 Express 管理的中间件和路由处理程序中抛出或拒绝的错误

next() 函数是在链中移动控制的机制。调用它,Express 就会调用下一个匹配的中间件。跳过它而不发送响应,请求就会无限期挂起。

中间件顺序很重要

Express 中间件按你注册的顺序执行。这不仅仅是一个细节——它是 Node.js 中间件模式的基础。

app.use(parseBody)
app.use(authenticate)
app.use(authorize)
app.get('/data', handler)

在这里,parseBody 首先运行,使请求数据可供 authenticate 使用。交换它们的顺序,身份验证就会失败,因为请求体还没有被解析。

这种顺序也会影响错误处理。错误处理中间件必须放在它保护的路由之后。

短路响应

中间件可以通过发送响应而不调用 next() 来提前结束请求-响应周期。这就是身份验证中间件拒绝未授权请求的方式:

function requireAuth(req, res, next) {
  if (!req.user) {
    return res.status(401).json({ error: 'Unauthorized' })
  }
  next()
}

一旦执行了 res.send()、res.json() 或类似方法,后续中间件就不会为该请求运行。这种短路是有意为之且很有用。

应用级、路由器级和路由级中间件

Express 中间件附加在不同的作用域:

应用级中间件为应用程序的每个请求运行。使用 app.use() 处理跨领域关注点,如日志记录或请求体解析。

路由器级中间件为匹配特定路由器的请求运行。这将中间件的作用域限定到路由组,而不影响整个应用程序。

路由级中间件仅为特定路由运行。将中间件函数直接传递给路由定义,以实现针对性行为,如验证。

这种区别在于作用域,而非能力。三者都使用相同的函数签名。

错误处理和 Express 5 中间件

Express 通过四参数签名识别错误处理中间件:(err, req, res, next)。当任何中间件调用 next(err) 或抛出错误时,Express 会跳过常规中间件并跳转到错误处理程序。

Express 5 改变了异步错误的工作方式。在 Express 4 中,被拒绝的 Promise 和异步异常需要手动处理或第三方包装器。Express 5 原生捕获来自异步函数的被拒绝的 Promise,并自动将它们路由到错误处理程序。

// Express 5: 不需要包装器
app.get('/data', async (req, res) => {
  const data = await fetchData() // 拒绝会触发错误中间件
  res.json(data)
})

app.use((err, req, res, next) => {
  res.status(500).json({ error: err.message })
})

错误处理中间件仍然需要最后注册,在路由和其他中间件之后。

结论

中间件是一种框架级模式,用于通过函数链处理请求。理解执行顺序、next() 的作用以及错误处理程序的放置位置,可以消除大多数中间件调试难题。

Express 5 的原生异步错误处理消除了一个常见痛点,但基本原理保持不变:按正确顺序注册中间件,调用 next() 或发送响应,并将错误处理程序放在最后。

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.