Express 项目环境搭建 -- 15. 路由模块化与 API 版本控制

路由是 Express 的核心。所有路由都写在 app.js 里,文件会迅速膨胀;用 express.Router() 把路由按资源拆开,再按版本组织目录,是更可持续的做法。

express.Router

Router 本身就是一个 mini 应用,可以挂载中间件和路由,再整体挂到主应用:

1
2
3
4
5
6
7
8
9
10
11
12
13
// src/routes/v1/users.js
const express = require("express");
const router = express.Router();

router.get("/", function (req, res) {
res.json({ list: [] });
});

router.get("/:id", function (req, res) {
res.json({ id: req.params.id });
});

module.exports = router;
1
2
3
// src/app.js
const usersRouter = require("./routes/v1/users");
app.use("/api/v1/users", usersRouter);

这样每个资源一个文件,路径前缀只在挂载时写一次。

按资源拆分

1
2
3
4
src/routes/v1/
├── users.js
├── articles.js
└── auth.js

路由文件只做「接收请求、调用业务逻辑、返回响应」,具体逻辑放到 controllers 或 services(见第 13 篇的目录约定)。

API 版本控制

接口一旦对外,旧客户端可能还在调用,不能直接改行为。常见做法是把版本放进 URL 路径:

1
2
/api/v1/users
/api/v2/users

对应目录也按版本分开:

1
2
src/routes/v1/users.js
src/routes/v2/users.js

版本迭代的原则是「新增而非修改」:v2 只增加字段或新语义,不改变 v1 已有行为;确实不兼容时,保留 v1 并标记废弃时间。

除了 URL 路径,也可以用请求头(如 Accept: application/vnd.example.v2+json)区分版本,但 URL 路径最直观、最容易调试,适合作为默认选择。

路由与中间件的顺序

路由挂载顺序决定了中间件的作用范围。鉴权中间件要挂在需要保护的路由之前:

1
2
3
app.use("/api/v1/auth", authRouter);        // 登录注册,不需要 token
app.use(authMiddleware); // 之后的都需要鉴权
app.use("/api/v1/users", usersRouter);

参考链接

系列导航


Express 项目环境搭建 -- 15. 路由模块化与 API 版本控制
https://bubao.github.io/posts/3c4d5e6f.html
作者
一念
发布于
2026年11月21日
许可协议