api-versioning-strategy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Versioning Strategy

API版本控制策略

Choose and implement API versioning approaches with proper deprecation timelines.

选择并实现API版本控制方案，配套合理的废弃时间线。

Versioning Methods

版本控制方法

Method	Example	Pros	Cons
URL Path	`/api/v1/users`	Clear, cache-friendly	URL clutter
Header	`API-Version: 1`	Clean URLs	Hidden, harder to test
Query	`?version=1`	Easy to use	Not RESTful

方法	示例	优点	缺点
URL路径	`/api/v1/users`	清晰、对缓存友好	URL冗余杂乱
请求头	`API-Version: 1`	URL简洁	隐式不直观、测试难度更高
查询参数	`?version=1`	使用简单	不符合RESTful规范

URL Path Versioning (Recommended)

URL路径版本控制（推荐方案）

javascript

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

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

javascript

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

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

Version Adapter Pattern

版本适配器模式

javascript

// Transform between versions
const v1ToV2 = (v1Response) => ({
  data: {
    type: 'user',
    id: v1Response.user_id,
    attributes: {
      name: v1Response.user_name,
      email: v1Response.email
    }
  }
});

javascript

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

Deprecation Headers

废弃提示请求头

javascript

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();
});

javascript

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();
});

Safe vs Breaking Changes

安全变更 vs 破坏性变更

Safe Changes (no version bump):

Adding optional fields
Adding new endpoints
Adding optional parameters

Breaking Changes (requires new version):

Removing fields
Changing field types
Restructuring responses
Removing endpoints

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

新增可选字段
新增新的接口端点
新增可选参数

破坏性变更（需要发布新版本）：

删除字段
修改字段类型
重构响应结构
删除接口端点

Deprecation Timeline

废弃时间线

Phase	Duration	Actions
Deprecated	3 months	Add headers, docs
Sunset Announced	3 months	Email users
Read-Only	1 month	Disable writes
Shutdown	-	Return 410 Gone

阶段	时长	操作
已废弃	3个月	添加废弃提示头、更新文档
已公告停运	3个月	邮件通知使用方
只读模式	1个月	禁用写入操作
正式停运	-	返回410 Gone状态码

Best Practices

最佳实践

Support N-1 versions minimum
Provide 6+ months migration window
Include migration guides with code examples
Monitor version usage to inform deprecation

至少支持N-1个历史版本
提供6个月以上的迁移窗口期
配套包含代码示例的迁移指南
监控版本使用数据，为废弃决策提供依据