使用 Claude Code 设计和实现 API 版本控制策略

API 版本控制的重要性

API 的破坏性变更会对客户端应用产生巨大影响。借助 Claude Code，你可以从版本控制策略设计到实现一站式完成。

三种版本控制方式

方式	示例	优点	缺点
URL 路径	/api/v1/users	清晰易懂	URL 会变化
请求头	API-Version: 1	URL 保持简洁	不易被发现
Accept	Accept: application/vnd.app.v1+json	符合 HTTP 标准	容易变得复杂

URL 路径方式的实现

这是最常见且最易理解的方式。

import express from "express";

const app = express();

// 按版本划分的路由
import v1Router from "./routes/v1";
import v2Router from "./routes/v2";

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

// routes/v1/users.ts
const v1Router = express.Router();

v1Router.get("/users", async (req, res) => {
  const users = await prisma.user.findMany();
  // v1 的响应格式
  res.json({
    data: users.map((u) => ({
      id: u.id,
      name: u.name,
      email: u.email,
    })),
  });
});

// routes/v2/users.ts
const v2Router = express.Router();

v2Router.get("/users", async (req, res) => {
  const users = await prisma.user.findMany({
    include: { profile: true },
  });
  // v2 的响应格式（添加分页）
  res.json({
    data: users.map((u) => ({
      id: u.id,
      fullName: u.name,
      email: u.email,
      profile: u.profile,
    })),
    pagination: {
      total: users.length,
      page: 1,
      perPage: 20,
    },
  });
});

请求头方式的实现

function versionMiddleware(
  req: express.Request,
  res: express.Response,
  next: express.NextFunction
) {
  const version = req.headers["api-version"] || "1";
  req.apiVersion = parseInt(version as string, 10);

  // 检查是否为支持的版本
  const supportedVersions = [1, 2, 3];
  if (!supportedVersions.includes(req.apiVersion)) {
    return res.status(400).json({
      error: `Unsupported API version: ${version}`,
      supportedVersions,
    });
  }

  // 已弃用版本的警告头
  if (req.apiVersion < 2) {
    res.set("Deprecation", "true");
    res.set("Sunset", "2026-06-01");
    res.set(
      "Link",
      '<https://api.example.com/docs/migration>; rel="deprecation"'
    );
  }

  next();
}

app.use("/api", versionMiddleware);

app.get("/api/users", async (req, res) => {
  switch (req.apiVersion) {
    case 1:
      return handleUsersV1(req, res);
    case 2:
      return handleUsersV2(req, res);
    default:
      return handleUsersV2(req, res);
  }
});

响应转换模式

通过转换层来吸收版本间差异的设计方案。

type UserV1 = {
  id: string;
  name: string;
  email: string;
};

type UserV2 = {
  id: string;
  fullName: string;
  emailAddress: string;
  createdAt: string;
};

const transformers = {
  1: (user: DBUser): UserV1 => ({
    id: user.id,
    name: user.name,
    email: user.email,
  }),
  2: (user: DBUser): UserV2 => ({
    id: user.id,
    fullName: user.name,
    emailAddress: user.email,
    createdAt: user.createdAt.toISOString(),
  }),
};

function createVersionedHandler<T>(
  fetcher: (req: express.Request) => Promise<T[]>,
  transformerMap: Record<number, (item: T) => unknown>
) {
  return async (req: express.Request, res: express.Response) => {
    const data = await fetcher(req);
    const transform = transformerMap[req.apiVersion];
    res.json({ data: data.map(transform) });
  };
}

弃用与迁移支持

function deprecationNotice(
  sunsetDate: string,
  migrationGuide: string
) {
  return (
    req: express.Request,
    res: express.Response,
    next: express.NextFunction
  ) => {
    res.set("Deprecation", "true");
    res.set("Sunset", sunsetDate);
    res.set("Link", `<${migrationGuide}>; rel="deprecation"`);

    console.warn(
      `Deprecated API v${req.apiVersion} accessed: ${req.path}`
    );

    next();
  };
}

// v1 计划于 2026 年 6 月废弃
app.use(
  "/api/v1",
  deprecationNotice(
    "2026-06-01",
    "https://docs.example.com/migration/v1-to-v2"
  ),
  v1Router
);

使用 Claude Code 实现的提示词示例

向 Claude Code 请求引入 API 版本控制时的提示词示例。API 设计基础请参阅 Claude Code 入门指南，错误处理请参阅错误边界设计。

为现有的 REST API 引入版本控制。
- URL 路径方式（/api/v1, /api/v2）
- v1 保持当前 API 不变
- v2 统一响应格式（添加 pagination）
- 为 v1 设置弃用头
- 同时生成迁移指南文档

API 版本控制的最佳实践可以参考 Microsoft REST API Guidelines。Claude Code 的使用方法请查看官方文档。

总结

API 版本控制是长期运维不可或缺的设计。借助 Claude Code 理解现有代码结构后再引入版本控制，可以在将对现有客户端的影响降至最低的同时持续演进 API。