5.1 Express中间件管道：从路由到错误链
5.1 Express 中间件管道：从路由到错误链
本节摘要：Express 是 Node 生态使用最广的 Web 框架，核心抽象只有两个：路由与中间件管道。本节从中间件的执行本质讲起，搭建一个结构清晰的 REST 服务，重点讲错误处理中间件的四参数契约、常用中间件的选配，以及顺序失误导致的经典故障。读完你能在心里画出每个请求流经的完整链条。
学习目标
- 能写出中间件并准确描述它的执行时机（next 之前与之后）
- 能组织多层路由避免单文件膨胀
- 能实现集中式错误处理与 404 兜底
- 能选配日志、体解析、安全等常用中间件
一、中间件到底是个什么
一个函数，签名 (req, res, next)。它拿到请求，做点事，然后要么结束响应，要么把接力棒交给 next()。Express 把一串中间件排成管道，请求像流水线上的工件依次穿过：
const express = require('express'); const app = express(); app.use((req, res, next) => { const start = Date.now(); res.on('finish', () => { console.log(`${req.method} ${req.url} ${res.statusCode} ${Date.now() - start}ms`); }); next(); // 不调用 next, 请求就永远停在这一站 }); app.get('/api/ping', (req, res) => { res.json({ pong: true }); }); app.listen(3000);
next 之前与之后是两个世界：之前的代码在「请求进入时」同步执行，之后的代码（如果写在 next() 调用后面）在「管道走完回头时」执行。这已经是一个朴素的洋葱模型——Express 回调风格下，大多数人只用「进去」这一半。
app.use((req, res, next) => { console.log('进入'); next(); console.log('回头'); // 所有后续中间件结束后才执行 });
⚠️ 常见坑：忘了调 next 且没结束响应，请求会悬到客户端超时——症状是「接口偶发挂起」，日志里什么都没有。
二、组织一个像样的 REST 服务
真实项目的骨架分四层：通用中间件、路由挂载、业务路由、错误兜底。
Express 中间件管道剖面
对应的最小完整代码：
const express = require('express'); const app = express(); app.use(express.json()); // 体解析：JSON 进 req.body const api = express.Router(); // 子路由：接口层 api.get('/orders/:id', async (req, res, next) => { try { const order = await getOrder(req.params.id); if (!order) return res.status(404).json({ error: '订单不存在' }); res.json(order); } catch (e) { next(e); // 交给错误链 } }); app.use('/api', api); app.use((req, res) => res.status(404).json({ error: '没有这个接口' })); // 404 兜底 app.use((err, req, res, next) => { // 错误处理：四参数，缺一不可 console.error(err.stack); const status = err.status || 500; res.status(status).json({ error: status === 500 ? '服务器内部错误' : err.message }); }); app.listen(3000);
四参数契约是新手最常踩的坑：错误处理中间件必须写满 (err, req, res, next) 四个形参，哪怕 next 没用到——Express 靠参数个数识别它的身份，少写一个就被当成普通中间件，错误链从此断裂。
三、常用中间件选配
| 需求 | 选择 | 要点 |
|---|---|---|
| JSON/表单体解析 | express.json / express.urlencoded | 挂在路由前；注意默认体积上限 |
| 静态文件 | express.static | 内部就是 Stream + pipe，天然背压 |
| 安全响应头 | helmet | 一行加齐防嗅探、防点击劫持等头 |
| 请求日志 | morgan | 开发期 dev 格式，生产期 combined |
| 跨域 | cors | 按需收紧白名单，别无脑全放开 |
| 限流 | express-rate-limit | 挡住突发流量，保护事件循环 |
选型原则一句话：能流式的别整块读，能默认收紧的别默认放开。express.json 的默认上限、cors 的星号配置，都是「默认值很方便、出事最方便」的典型。
四、顺序失误的两个经典故障
故障一：路由挂在体解析之前，POST 接口里 req.body 恒为 undefined。顺序错了，管道没机会先解析。故障二：404 兜底写在业务路由之前，所有请求都吃 404。中间件管道是严格按注册顺序执行的，「写在哪」就是「何时执行」，这类问题不需要调试器，画一遍管道剖面图就能定位。
💡 关键直觉：读 Express 项目的第一步是打开入口文件，从上到下把 use 与路由抄成一张管道清单——八成的问题（挂起、404、body 为空）都在清单的顺序里。
性能与结构的一体两面
框架层的性能注意力放在两处：中间件数量与路由结构。每个请求要穿过整条中间件链，链上挂着的重量级件越多，无谓开销越大——把只需要在特定路由生效的中间件挂到对应 Router 而不是全局，是最直接的减负。路由组织则建议按资源域拆分 Router 文件，入口只做装配；这不仅是美观问题，路由表越扁平，越容易在出问题时快速定位是哪一段管道的责任。
从框架回到地基
最后回到一个观念：无论框架多成熟，第 3 章的地基知识永远在下面垫着。响应是流、请求是流、背压规则不变——当框架报出「写缓冲溢出」或接口在大响应下内存上涨时，能救你的不是框架文档，而是你对手写服务器与流模型的理解。框架让你写得快，地基让你修得快，两手都要硬。
本节要点回顾
- 中间件即工位：
(req, res, next)，要么 next 交棒，要么结束响应，二者必居其一。 - 洋葱的雏形：next 之后的代码在回程执行，Express 风格下常被遗忘。
- 错误链契约：四参数缺一不可；业务代码 try/catch 后 next(e) 上抛。
- 404 垫底：所有路由之后放兜底，语义才完整。
- 顺序即语义：解析在前、兜底在后，画管道清单是排查第一步。