api-versioning-strategy

API 版本管理策略

目录

• 概述
• 适用场景
• 快速开始
• 参考指南
• 最佳实践

概述

全面介绍 REST API、GraphQL 和 gRPC 服务的 API 版本管理方法、弃用策略、向后兼容技术和迁移规划。

适用场景

• 从一开始就为新 API 设计版本管理
• 为现有 API 添加不兼容变更
• 弃用旧版 API
• 规划 API 迁移
• 确保向后兼容
• 同时管理多个 API 版本
• 为不同版本编写 API 文档
• 实现 API 版本路由

快速开始

最小可运行示例：

// express-router.ts
import express from "express";

const app = express();

// Version 1
app.get("/api/v1/users", (req, res) => {
  res.json({
    users: [{ id: 1, name: "John Doe" }],
  });
});

// Version 2 - Added email field
app.get("/api/v2/users", (req, res) => {
  res.json({
    users: [{ id: 1, name: "John Doe", email: "[email protected]" }],
  });
});

// Shared logic with version-specific transformations
app.get("/api/:version/users/:id", async (req, res) => {
  const user = await userService.findById(req.params.id);

  if (req.params.version === "v1") {
    res.json({ id: user.id, name: user.name });
// ... (see reference guides for full implementation)

参考指南

references/ 目录中的详细实现：

指南	内容
版本管理方法	版本管理方法
向后兼容模式	向后兼容模式
弃用策略	弃用策略
迁移指南示例	迁移指南示例
响应结构	响应结构
日期格式	日期格式、错误格式
JavaScript/TypeScript	JavaScript/TypeScript、Python
GraphQL 版本管理	GraphQL 版本管理
gRPC 版本管理	gRPC 版本管理
版本检测与路由	版本检测与路由
测试多个版本	测试多个版本
模式 1：版本无关的核心	模式 1：版本无关的核心、模式 2：用于渐进式发布的功能标志、模式 3：API 版本指标

最佳实践

✅ 应该做

• 从第一天起就进行版本管理（即使是 v1）
• 记录不兼容和兼容变更
• 提供清晰的迁移指南，并附上代码示例
• 遵循语义化版本原则
• 提前 6-12 个月发出弃用通知
• 监控已弃用 API 的使用情况
• 向 API 使用者发送弃用警告
• 至少同时支持 2 个版本
• 使用适配器/转换器处理版本逻辑
• 测试所有受支持的版本
• 记录正在使用的 API 版本
• 尽可能提供迁移工具
• 保持版本管理方法一致

❌ 不应该做

• 不进行版本管理就更改 API 行为
• 不事先通知就移除版本
• 支持过多版本（>3）
• 在同一个 API 中采用不同的版本管理策略
• 不提升版本号就破坏 API
• 忘记更新文档
• 过快弃用（<6 个月）
• 忽视 API 使用者的反馈
• 把每项变更都作为新版本
• 不一致地使用版本号