Node.js Express 后端开发指南：路由、中间件与错误处理

在 JavaScript 生态里，Node.js + Express 是构建后端 API 最主流的组合之一。Express 是一个极简但灵活的 Web 框架，它不替你做太多决定，而是把"请求如何到达、如何处理、如何返回"的控制权交给你。根据 Node.js 官方与 Express 官方文档，本文梳理出后端开发最核心的四块内容：路由、中间件、错误处理与项目结构。

环境准备与项目初始化

先确认本机已安装 Node.js（建议 LTS 版本），然后初始化项目：

mkdir my-api && cd my-api
npm init -y
npm install express

用 npm init -y 生成 package.json 后，require('express') 即可创建应用实例。Express 本身不强制目录结构，但配合模块化拆分，后续维护会轻松很多。

Express 路由：入口与参数

路由决定了应用的端点（URI）如何响应客户端请求。Express 的路由方法对应 HTTP 方法，例如 app.get() 处理 GET、app.post() 处理 POST：

const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello World');
});

app.get('/users/:userId', (req, res) => {
  res.json({ userId: req.params.userId });
});

app.listen(3000);

:userId 是命名路由参数，会被捕获进 req.params。如果多个 HTTP 方法共享同一路径，可以用 app.route() 链式定义；需要把一组相关路由拆成独立模块时，则用 express.Router，它被官方称为"mini-app"：

// routes/users.js
const router = express.Router();
router.get('/', (req, res) => res.json({ users: [] }));
module.exports = router;

然后在主应用中挂载：app.use('/api/users', usersRouter)。这样每个资源一个文件，路由规模变大后依然清晰。

中间件：请求处理流水线

中间件是 Express 的"流水线"机制。每个中间件函数接收 req、res 和 next 三个参数，可以做任意处理，然后调用 next() 把控制权交给下一个中间件。关键规则是：加载顺序即执行顺序，而且如果当前中间件没有终止请求-响应循环，就必须调用 next()，否则请求会一直挂起。

官方文档里最典型的例子是自定义日志中间件：

const myLogger = function (req, res, next) {
  console.log('LOGGED');
  next();
};
app.use(myLogger);

常见的第三方中间件还包括：express.json() 解析 JSON 请求体、cors 处理跨域、helmet 加固 HTTP 头。如果你做的是前后端分离或移动端 App，CORS 基本是必配项。

错误处理：统一兜底

Express 识别错误处理中间件的方式是多一个 err 参数：

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

它必须放在所有路由之后。配合 404 兜底路由，可以形成完整闭环：先匹配不到任何路由时返回 404，再进入错误处理。对于异步代码，Express 5 会自动捕获 Promise 的 rejection 并交给错误中间件，因此尽量用 async 函数写路由，能省去大量手写 try/catch。

把 404 兜底、请求日志与统一错误处理串起来，就是一个可以直接跑的最小应用（morgan 需先 npm install）：

const express = require('express');
const app = express();

app.use(express.json());
app.use(morgan('combined'));

app.get('/health', (req, res) => res.json({ ok: true }));

app.use((req, res, next) => {
  res.status(404).json({ error: 'Not Found' });
});

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

app.listen(3000);

顺序很关键：express.json() 与日志放最前，业务路由居中，404 兜底和错误处理放最后。新手最常见的错误是把错误处理中间件放在路由之前，那样错误永远到不了它手里。

如果项目从零开始，建议直接用 Express 5。它和 4 的主要差异集中在异步错误处理上：

维度 Express 4 Express 5
异步错误 需手动 try/catch 自动捕获 Promise rejection
路径语法 path-to-regexp 0.x path-to-regexp 8.x
通配符写法 * /*splat 等新语法
生态兼容 兼容 兼容主流中间件

升级老项目时，通配符路由的写法变化是最容易踩的坑，迁移前先跑一遍测试。

常用能力与安全加固

在路由之外，还有几个高频能力值得掌握。解析 JSON 请求体用 app.use(express.json())；处理跨域用 cors 包；为响应头补充安全字段、限制请求体大小可以用 helmet。生产环境建议开启 trust proxy 以在反代后正确读取客户端 IP，并接入统一访问日志（如 morgan）与集中式错误上报。如果接口需要鉴权，可以在中间件里校验 JWT，把用户信息挂到 req 上，后续路由直接读取，避免每个 handler 重复做认证逻辑。

推荐项目结构

  • app.js：创建 Express 实例、挂载全局中间件与路由；
  • server.js：启动监听（app.listen）；
  • routes/：按资源拆分路由；
  • controllers/：业务逻辑；
  • middleware/：认证、日志、校验等中间件；
  • models/ 或 services/：数据访问层。

这种分层让每个文件的职责单一，配合测试也更容易。更完整的可运行示例可以参考本站 Node.js REST API 示例。

一个真实场景：三人团队的产品 API

假设一个三人团队要为 SaaS 写 REST API，涉及用户、订单与支付回调。他们的做法是：routes/ 下按资源拆成 users.js、orders.js，middleware/ 里放 JWT 鉴权与参数校验，services/ 里放业务逻辑，异步路由一律用 async 写法。上线后最常踩的是两个坑：一是某个中间件忘了 next()，请求像被"吞掉"一样一直转圈，只能靠日志排查；二是 CORS 在本地联调时一切正常，一上生产就被浏览器跨域拦截。前者靠代码评审加请求日志，后者在项目初始化时就要把跨域配置按正式域名写对，别等部署后才想起来。

16IDC 观察

对独立开发者和小团队而言，Express 的学习曲线最平缓：一个文件就能跑起接口，配合 Vercel、Render 或云服务器即可上线。建议先把 API 对接基础打牢，先读 网站 API 集成基础指南；上线前务必规划好 API 错误处理与重试策略。更多后端开发内容见 后端对接 分类。

参考：Express 路由指南 https://expressjs.com/en/guide/routing.html · Express 中间件 https://expressjs.com/en/guide/using-middleware.html · Express 错误处理 https://expressjs.com/en/guide/error-handling.html
原文来源：https://expressjs.com/en/guide/routing.html