api-versioning-deprecation-planner

API 版本管理与弃用规划

安全地演进 API，同时不破坏现有客户端。

版本管理策略

URL 版本管理（推荐）

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

优点： 清晰、易于路由、便于编写文档
缺点： 版本过多时会造成 URL 冗余

标头版本管理

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

优点： URL 简洁
缺点： 更难测试，且不够直观

查询参数

/api/users?version=1

优点： 易于实现
缺点： 不符合 REST 风格，容易遗漏

弃用时间线

# API Deprecation Plan: v1 → v2

## Timeline (6 months)

### Month 1: Announcement

- [ ] Publish deprecation notice in changelog
- [ ] Email all API consumers
- [ ] Add deprecation headers to v1 responses
- [ ] Update documentation with migration guide

### Month 2-4: Migration Period

- [ ] v2 fully available
- [ ] Both v1 and v2 supported
- [ ] Track v1 usage metrics
- [ ] Offer migration support

### Month 5: Final Warning

- [ ] Email reminder to remaining v1 users
- [ ] Increase deprecation warning visibility
- [ ] Offer 1-on-1 migration help

### Month 6: Sunset

- [ ] Disable v1 endpoints
- [ ] Return 410 Gone with migration instructions
- [ ] Monitor for issues

弃用响应标头

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Link: <https://api.example.com/v2/users>; rel="alternate"
Warning: 299 - "This API version is deprecated. Migrate to v2 by Dec 31, 2024"

破坏性与非破坏性更改

非破坏性（安全）

✅ 添加新端点
✅ 添加可选请求参数
✅ 在响应中添加字段
✅ 添加新的响应状态码
✅ 将必填字段改为可选

破坏性（需要新版本）

❌ 移除端点
❌ 移除请求参数
❌ 移除响应字段
❌ 更改字段类型
❌ 将可选字段改为必填
❌ 更改身份验证方式

迁移指南模板

# Migration Guide: API v1 → v2

## What's Changing

### Authentication

**v1:** API Key in query param

GET /api/v1/users?api_key=xxx

**v2:** Bearer token in header

GET /api/v2/users Authorization: Bearer xxx

### Response Format
**v1:** Snake case
```json
{"user_id": 123, "first_name": "John"}

v2： 驼峰命名

{ "userId": 123, "firstName": "John" }

分页

v1： 基于页码

GET /api/v1/users?page=2&per_page=10

v2： 基于游标

GET /api/v2/users?cursor=abc123&limit=10

分步迁移

步骤 1：更新身份验证

将查询参数身份验证改为基于标头的身份验证：

- axios.get('/api/v1/users?api_key=xxx')
+ axios.get('/api/v2/users', {
+   headers: { 'Authorization': 'Bearer xxx' }
+ })

步骤 2：更新响应处理

调整字段名称的大小写：

- const userId = data.user_id
+ const userId = data.userId

步骤 3：更新分页

切换为基于游标的分页：

- const nextPage = page + 1
- fetch(`/api/v1/users?page=${nextPage}`)
+ const cursor = data.meta.next_cursor
+ fetch(`/api/v2/users?cursor=${cursor}`)

测试迁移

# 1. Test v2 in development
curl -H "Authorization: Bearer xxx" https://dev-api.example.com/v2/users

# 2. Run v1 and v2 side-by-side in staging
# Compare responses for consistency

# 3. Gradual rollout in production
# Route 10% → 50% → 100% traffic to v2

支持资源

• API v2 文档
• 迁移示例仓库
• 支持频道

## Backward Compatibility Strategies

### 1. Parallel Versions
Run v1 and v2 simultaneously:
```typescript
app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

2. 适配器模式

v1 通过适配器在内部调用 v2：

// v1 endpoint
router.get("/api/v1/users", async (req, res) => {
  // Call v2
  const v2Response = await v2Controller.getUsers(req);

  // Adapt v2 response to v1 format
  const v1Response = adaptV2ToV1(v2Response);

  res.json(v1Response);
});

3. 功能标志

逐步推出功能：

if (req.version === "v2" && featureFlags.newPagination) {
  return cursorBasedPagination(req);
} else {
  return pageBasedPagination(req);
}

客户端沟通计划

公告邮件模板

Subject: [ACTION REQUIRED] API v1 Deprecation - Migrate by Dec 31

Hi API Consumers,

We're deprecating API v1 on December 31, 2024. Please migrate to v2.

What's changing:
- Authentication: API keys → Bearer tokens
- Response format: snake_case → camelCase
- Pagination: page-based → cursor-based

Migration resources:
- Guide: https://docs.example.com/migration
- Examples: https://github.com/example/v2-examples
- Support: [email protected]

Timeline:
- Now: v2 available, v1 still works
- Oct 31: v1 will show deprecation warnings
- Dec 31: v1 will be shut down

Questions? Reply to this email.

监控迁移进度

// Track version usage
app.use((req, res, next) => {
  const version = req.path.includes('/v1') ? 'v1' : 'v2';
  metrics.increment('api.requests', { version });
  next();
});

// Dashboard metrics
- v1 requests/day: 10,000 → 5,000 → 1,000 → 0
- v2 requests/day: 0 → 5,000 → 9,000 → 10,000
- Unique v1 consumers: 50 → 25 → 5 → 0

回滚计划

## If Migration Goes Wrong

### Symptoms

- Spike in 5xx errors
- Client complaints
- Revenue impact

### Rollback Steps

1. Re-enable v1 endpoints
2. Update deprecation timeline
3. Communicate delay to clients
4. Fix issues in v2
5. Resume migration when stable

最佳实践

1. 尽早公告：至少提前 6 个月通知
2. 提供工具：SDK、迁移脚本
3. 支持客户端：必要时提供一对一帮助
4. 监控使用情况：跟踪仍在使用 v1 的用户
5. 逐步停止服务：不要让用户措手不及
6. 文档清晰：提供分步指南
7. 提供宽限期：为大型客户端延长宽限期

输出检查清单

• 已选择版本管理策略
• 已制定弃用时间线（至少 6 个月）
• 已编写迁移指南
• 已记录破坏性更改
• 已制定向后兼容计划
• 已起草客户端沟通内容
• 已设置监控仪表板
• 已记录回滚计划
• 已准备支持资源