SuperAPI AI 工具集

api-versioning

编程与开发

查看项目

更新于 10-16 06:15

技能介绍

用途:在API响应或请求出现破坏性变更时,创建版本变更文件,在不同版本之间转换数据。核心思路是始终构建最新格式,再自动向后兼容转换。响应转换方向为新→旧(用户期望旧格式),请求转换方向为旧→新(处理程序期望最新格式);每个变更文件只做单步映射,从一个版本映射到前一个版本。

主要能力与用法:变更文件按资源放在shared/api/{resource}/changes/(响应转换,顶层资源)或shared/api/{resource}/requestChanges/(请求转换),旧结构定义放previousVersions/,统一在shared/api/versionUtils/versionChangeRegistry.ts注册。创建步骤:先在shared/api/{resource}/定义新旧schema,再用defineVersionChange编写变更文件并指定newVersion、oldVersion、description、affectedResources、newSchema、oldSchema以及transformResponse,最后在注册表登记。嵌套模型(如ApiCustomer内的ApiSubscription)不注册,改为导出transform函数供父级转换调用。请求转换需设affectsRequest: true、affectsResponse: false并实现transformRequest。处理程序可自动版本化(如getApiCustomer),也可调用applyResponseVersionChanges做手动响应版本化;路由可用versionedBody/versionedQuery按版本声明校验schema。若业务逻辑仍绑定旧模型,可在处理程序内按ctx.apiVersion转换。行为类变更可用hasSideEffects配合backwardsChangeActive检查。文件命名以目标(更旧)版本为准,如V1.2_CustomerChange.ts、VX.Y_ResourceQueryChange.ts,并建议用satisfies保证返回类型与schema一致。

限制:资料未提供安装命令、依赖版本或运行环境要求;部分代码细节需参考仓库内相关工具与类型定义。