基于Node.js、Express和Swagger的API版本化实现咨询

一、文件系统结构优化 #

你考虑的按版本目录拆分的方案是合理的，属于版本优先的结构，能清晰隔离不同版本的路由和文档，避免混乱。可以在此基础上补充细节：

• 保留routes/v1、routes/v2的分层，每个版本下维护各自的资源路由（users/books等）
• 如果存在跨版本复用的工具函数、中间件，建议抽离到routes/common目录，避免重复代码
• 每个版本的路由入口新增routes/vX/index.ts，统一导出该版本的所有路由，方便Express批量注册

示例结构：

routes:
  common:
    - auth.middleware.ts
    - response.util.ts
  v1:
    - index.ts       # 导出v1所有路由
    - users
      - index.ts
      - docs.ts
    - books
      - index.ts
      - docs.ts
    - magazines
      - index.ts
      - docs.ts
  v2:
    - index.ts       # 导出v2所有路由
    - users
      - index.ts
      - docs.ts

二、Swagger文档适配多版本 #

方案1：生成独立的版本化文档（推荐） #

为每个API版本单独生成Swagger文档，通过不同路径访问：

• 在routes/vX/下新增swagger.ts，定义该版本的Swagger基础配置（版本号、标题、描述）
• 每个资源的docs.ts仅维护对应版本的API文档定义
• 在Express中注册两个Swagger UI路由，比如/api/v1/docs和/api/v2/docs，分别加载对应版本的文档配置

这种方案版本隔离彻底，符合开发者使用习惯，避免单文档过于臃肿。

方案2：单文档内分版本章节 #

如果希望在同一个Swagger页面展示所有版本，可以按版本分组：

• 在Swagger的tags中为每个资源加上版本标识，比如{name: "v1 - Users", description: "用户接口v1版本"}、{name: "v2 - Users", description: "用户接口v2版本"}
• 每个资源的docs.ts中，将接口的tags指定为对应版本的标签
• 最终Swagger文档会按标签分组展示，清晰区分不同版本的接口

三、自动识别路由的最新版本 #

方法1：目录扫描+版本排序（适合小项目） #

项目启动时，扫描routes目录下的版本文件夹，按版本号排序取最大值：

import fs from 'fs';
import path from 'path';

function getLatestApiVersion() {
  const routesDir = path.join(__dirname, 'routes');
  const versions = fs.readdirSync(routesDir)
    .filter(dir => dir.startsWith('v') && !isNaN(parseInt(dir.slice(1))))
    .sort((a, b) => parseInt(b.slice(1)) - parseInt(a.slice(1)));
  return versions[0] || 'v1';
}

// 使用示例：注册最新版本路由
const latestVersion = getLatestApiVersion();
const latestRoutes = require(`./routes/${latestVersion}`);
app.use(`/api/${latestVersion}`, latestRoutes);

方法2：维护版本映射配置文件（适合多资源更新节奏不一致的场景） #

在项目根目录创建api-versions.json，记录每个资源的最新版本：

{
  "users": "v2",
  "books": "v1",
  "magazines": "v1"
}

然后写一个中间件，根据请求路径自动转发到对应版本：

import versionConfig from '../api-versions.json';

app.use('/api/latest/:resource', (req, res, next) => {
  const { resource } = req.params;
  const latestVersion = versionConfig[resource] || 'v1';
  // 重定向到最新版本的路由
  req.url = `/api/${latestVersion}/${resource}${req.url.slice(req.url.indexOf('?') || req.url.length)}`;
  next();
});

方法3：路由注册时自动标记版本 #

在每个版本的路由文件中，导出时附带版本信息，统一收集后构建最新版本映射表：

// routes/v2/users/index.ts
export default {
  version: 'v2',
  resource: 'users',
  router: express.Router()
  // ... 路由定义
};

主入口收集所有路由后，按资源分组排序，自动记录每个资源的最新版本。

总结 #

• 文件结构优先选择版本分层方案，配合公共目录复用代码
• Swagger推荐用独立版本文档，提升开发者体验
• 自动识别最新版本可根据项目规模选择：小项目用目录扫描，多资源场景用配置文件

内容的提问来源于stack exchange，提问作者MayAsk