如何在 Node.js 中实现 API 版本控制策略（2026 指南）

Source: Dev.to

为什么 API 版本化很重要

每一次对 API 的更改都有可能导致现有客户端出现问题。无论你是：

• 删除字段
• 更改响应格式
• 弃用端点

版本化为客户端提供了所需的稳定性，同时你可以演进你的 API。

“API 是一种合同。版本化是你在前进的同时遵守该合同的方式。”

Source: …

策略 1：URL 路径版本化（最常见）

版本号包含在 URL 路径中：

GET /api/v1/users
GET /api/v2/users

在 Express 中的实现

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

// v1 routes
app.get("/api/v1/users", (req, res) => {
  res.json({
    users: [{ id: 1, name: "Alice", email: "alice@example.com" }],
  });
});

// v2 routes – added avatar field
app.get("/api/v2/users", (req, res) => {
  res.json({
    users: [
      {
        id: 1,
        name: "Alice",
        email: "alice@example.com",
        avatar: "https://example.com/alice.png",
      },
    ],
  });
});

app.listen(3000);

优点

• 清晰且显式
• 易于测试和调试
• 与缓存配合良好

缺点

• URL 污染
• 需要路由逻辑

策略 2：Header 版本控制（更优雅）

客户端在 HTTP 头部指定版本：

GET /api/users
Accept-Version: v1

实现

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

// Middleware to extract version
const versionMiddleware = (req, res, next) => {
  const version = req.headers["accept-version"] || "v1";
  req.apiVersion = version;
  next();
};

app.use(versionMiddleware);

app.get("/api/users", (req, res) => {
  const { apiVersion } = req;

  const baseUser = { id: 1, name: "Alice", email: "alice@example.com" };

  if (apiVersion === "v2") {
    res.json({
      users: [{ ...baseUser, avatar: "https://example.com/alice.png" }],
    });
  } else {
    res.json({ users: [baseUser] });
  }
});

app.listen(3000);

优点

• 更简洁的 URL
• 与版本无关的端点

缺点

• 对消费者来说不够直观
• 需要管理请求头

策略 3：查询参数版本控制

将版本作为查询参数传递：

GET /api/users?version=1
GET /api/users?version=2

实现

app.get("/api/users", (req, res) => {
  const version = parseInt(req.query.version) || 1;

  const baseUser = { id: 1, name: "Alice", email: "alice@example.com" };

  if (version >= 2) {
    res.json({
      users: [{ ...baseUser, avatar: "https://example.com/alice.png" }],
    });
  } else {
    res.json({ users: [baseUser] });
  }
});

优点

• 易于实现
• 客户端可以快速选择使用

缺点

• 可能导致缓存问题
• 相比路径版本化语义性较弱

策略 4：内容协商（最符合 REST 的方式）

使用带有自定义媒体类型的 Accept 头部：

GET /api/users
Accept: application/vnd.yourapi.v1+json

实现

const versionMiddleware = (req, res, next) => {
  const acceptHeader = req.headers.accept || "";
  // Extract version from "application/vnd.yourapi.v1+json"
  const match = acceptHeader.match(/v(\d+)/);
  req.apiVersion = match ? parseInt(match[1]) : 1;
  next();
};

app.use(versionMiddleware);

app.get("/api/users", (req, res) => {
  const version = req.apiVersion;
  // Handle versioning based on `req.apiVersion`
  // (implementation omitted for brevity)
});

优点

• 符合 HTTP 标准
• 支持细粒度的媒体类型协商

专业提示：使用路由库

对于更大的项目，可以使用独立的路由器来组织不同版本：

const { Router } = require("express");
const v1Router = Router();
const v2Router = Router();

// v1 routes
v1Router.get("/users", (req, res) => {
  res.json({ version: "v1", data: [] });
});

// v2 routes
v2Router.get("/users", (req, res) => {
  res.json({ version: "v2", data: [], meta: {} });
});

app.use("/api/v1", v1Router);
app.use("/api/v2", v2Router);

API 版本管理最佳实践

• 始终从第一天起进行版本控制 – 不要等到需要更改时才开始。
• 至少支持两个版本 – 给客户端留出迁移时间。
• 明确传达废弃信息 – 使用 Deprecation 头部和警告字段。
• 为每个版本编写文档 – 为每个版本保留独立文档。
• 设定废弃时间表 – 例如，“v1 将在 6 个月后废弃”。

示例废弃响应

app.get("/api/v1/users", (req, res) => {
  res.set("Deprecation", "true");
  res.set("Sunset", "Sat, 01 Aug 2026 00:00:00 GMT");
  res.set("Link", '; rel="latest version"');

  res.json({
    users: [],
    warning: "This endpoint will be deprecated on August 1, 2026",
  });
});

哪种策略适合您？

对于大多数项目来说，URL 路径版本化 在 2026 年仍然是首选。它明确、友好缓存且易于理解。

结论

API 版本管理不是可选的——它对于维护稳定的集成至关重要。首先使用 URL 路径版本进行简单实现，并根据需要演进你的策略。

记住： 你的 API 客户端信任你不会破坏他们的代码。版本管理是你在持续创新的同时兑现此承诺的方式。

祝编码愉快！ 🚀