mcpField
A
api-versioning-strategy

api-versioning-strategy

github.com/secondsky开发242405 次安装5 周前更新
代码仓库

关于 api-versioning-strategy

面向开发者的 API 版本管理 Skill，涵盖版本方案选择、实现与弃用规划，并提供适配器和分阶段退役模式。

主要功能

  1. 01比较路径、请求头和查询参数版本管理
  2. 02展示 URL 路径路由配置
  3. 03说明版本适配器模式
  4. 04区分安全变更与破坏性变更
  5. 05规划弃用时间线

适用场景

  1. 01为新 API 选择版本管理方式
  2. 02新增版本并保留旧路由
  3. 03规划客户端迁移与接口退役

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/secondsky/claude-skills --skill api-versioning-strategy

安装后在 Claude Code 中输入/api-versioning-strategy确认已加载。

详细介绍

API 版本控制策略

选择并实施 API 版本控制方法，并制定适当的弃用时间表。

版本控制方法

方法示例优点缺点
URL 路径/api/v1/users清晰，利于缓存URL 冗长
请求头API-Version: 1URL 简洁不明显，较难测试
查询参数?version=1易于使用不符合 RESTful 风格

URL 路径版本控制（推荐）

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

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

版本适配器模式

// Transform between versions
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();
});

安全变更与破坏性变更

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

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

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

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

弃用时间表

阶段时长操作
已弃用3 个月添加请求头和文档
已宣布日落时间3 个月给用户发送电子邮件
只读1 个月禁用写入操作
关闭-返回 410 Gone

最佳实践

  • 至少支持 N-1 个版本
  • 提供 6 个月以上的迁移窗口
  • 提供包含代码示例的迁移指南
  • 监控版本使用情况，以便制定弃用计划

评论

支持 Markdown