用途
api-versioning 用于为 REST 和 GraphQL API 做版本管理。当用户需要为 API 增加版本、处理破坏性变更、实施 API 弃用、管理多个 API 版本时适用。其核心目标是:API 会持续演进,但破坏性变更会破坏客户端,因此需要用版本化策略与弃用流程来平衡演进与兼容。
主要能力
该技能覆盖以下内容:
- 版本化策略:URL 路径、请求头、查询参数。
- 弃用工作流。
- 向后兼容变更的识别。
- 面向 REST 与 GraphQL API 的迁移模式。
使用方式
技能以分步指令的形式给出操作流程。
第一步:URL 路径版本化(推荐)
为不同版本创建独立路由文件,例如 routes/v1/projects.ts 与 routes/v2/projects.ts。示例中 v1 的 GET /projects 直接从数据库查询并返回扁平数组;v2 的同一路径支持 cursor 与 limit 查询参数,返回带分页信封的结构:
{
data: projects,
pagination: {
nextCursor: hasMore ? projects[projects.length - 1].id : null,
hasMore,
},
}
分页实现中取 limit + 1 条记录,若超出则 pop 掉最后一条,以判断是否还有更多数据。随后在 app.ts 中分别挂载:
app.use('/v1', v1Router)
app.use('/v2', v2Router)
第二步:向后兼容变更
资料明确列出了无需升级版本的“安全”变更与需要新版本的“破坏性”变更。
无需版本升级的安全变更:
- 在响应中新增可选字段。
- 新增端点。
- 新增可选查询参数。
- 新增枚举值(前提是客户端能处理未知值)。
需要新版本的破坏性变更:
- 删除或重命名字段。
- 更改字段类型。
- 将可选字段改为必填。
- 更改响应结构(例如数组 → 对象)。
- 更改认证方案。
示例对比:V1 响应 { id, name, status },V1.1 响应新增 taskCount 字段属于安全变更,旧客户端会忽略新字段;而把 V1 的数组响应改为 V2 的 { data: [...], pagination: {} } 结构则属于破坏性变更,需要新版本。
第三步:弃用响应头
提供一个 deprecationMiddleware 中间件工厂,接收 version 与 sunsetDate 参数,返回一个 Express 中间件,在响应中设置:
- Deprecation: true
- Sunset: sunsetDate(RFC 8594)
- Link:
</v2${req.path}>; rel="successor-version"
同时打印弃用日志,记录请求方法、被弃用版本路径与来源 IP,然后调用 next()。使用方式为在挂载路由时传入弃用日期,例如:
app.use('/v1', deprecationMiddleware('1', 'Sat, 01 Jun 2026 00:00:00 GMT'), v1Router)
第四步:API 变更日志
技能给出变更日志的格式示例。v2.0.0 条目下列出破坏性变更(GET /projects 改为返回分页结构 { data: [], pagination: {} };移除 GET /projects/all,改用分页),并提供迁移指南(更新响应解析以读取 response.data;为大数据集实现基于游标的分页;v1 下线日期为 2026 年 6 月 1 日)。v1.3.0 条目下列出新增内容(项目响应中的 taskCount 字段、GET /projects/{id}/activity 端点)。
指南要点
- URL 路径版本化(/v1/、/v2/)最简单且被最广泛采用。
- 仅对破坏性变更创建新的主版本,其余一律采用增量方式。
- 弃用后旧版本至少继续保持运行 6 至 12 个月。
- 监控旧版本使用量,在流量接近零之前不要下线。
- 为每一次破坏性变更编写迁移指南。
- 可考虑使用 API 网关(Kong、AWS API Gateway)来独立路由不同版本。
适用场景
需要为 API 增加版本、处理破坏性变更、实施 API 弃用、管理多个 API 版本,或为 REST / GraphQL API 制定迁移与兼容策略的开发场景。
限制
资料主要基于 TypeScript/Express 示例,未提供其他语言或框架的具体实现;未说明对 GraphQL 版本化的具体代码示例,仅在概述中提及覆盖 GraphQL API;未提供该技能的安装方式、收费信息或价格;未提供关于性能、兼容性验证或测试方法的具体说明。上述未提及的内容暂未提供。