API版本化策略 api-versioning-strategy

---

名称: api-versioning-strategy 描述: 使用URL路径、头部或查询参数实现API版本化，具有向后兼容性和弃用策略。适用于管理多个API版本、规划破坏性更改或设计迁移路径。

API 版本化策略

选择和实现API版本化方法，并设置适当的弃用时间线。

版本化方法

方法	示例	优点	缺点
URL路径	/api/v1/users	清晰，缓存友好	URL冗余
头部	API-Version: 1	干净的URL	隐藏，测试困难
查询	?version=1	易于使用	不符合RESTful

URL路径版本化（推荐）

const v1Router = require('./routes/v1');
const v2Router = require('./routes/v2');

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

版本适配器模式

// 版本间转换
const v1ToV2 = (v1Response) => ({
  data: {
    type: 'user',
    id: v1Response.user_id,
    attributes: {
      name: v1Response.user_name,
      email: v1Response.email
    }
  }
});

弃用头部

app.use('/api/v1', (req, res, next) => {
  res.setHeader('Deprecation', 'true');
  res.setHeader('Sunset', 'Sat, 01 Jun 2025 00:00:00 GMT');
  res.setHeader('Link', '</api/v2>; rel="successor-version"');
  next();
});

安全变更 vs 破坏性变更

安全变更（无需版本升级）:

• 添加可选字段
• 添加新端点
• 添加可选参数

破坏性变更（需要新版本）:

• 移除字段
• 更改字段类型
• 重构响应
• 移除端点

弃用时间线

阶段	持续时间	操作
已弃用	3个月	添加头部，文档
宣布弃用	3个月	邮件通知用户
只读	1个月	禁用写入
关闭	-	返回410 Gone

最佳实践

• 最少支持N-1个版本
• 提供6个月以上的迁移窗口
• 包括带有代码示例的迁移指南
• 监控版本使用情况以指导弃用