用途:作为 API 生命周期策略技能,产出一份书面的版本与弃用政策,覆盖版本由哪种方案承载、何为破坏性变更、消费者在版本停用前获得多长缓冲、如何沟通与执行下线,以及谁批准破坏性改动。资料强调难点在于“在不破坏仍在用旧版消费者的前提下移除一个版本”。
主要能力:按范式区分策略——REST/HTTP 默认“版本化加日落”,GraphQL 默认持续模式演进(用 @deprecated 标记,但该标记只是文档与工具信号,不是移除机制);gRPC 的破坏性变更定义、通知期与治理同样适用,方案与执行交由同系列的 public-grpc-api-design。政策层与审查层分工:本技能决定方案与生命周期规则,public-api-design-review 仅在评审时检查方案是否存在并一致。SDK 另有版本体系,需单独撰写。
使用方式:先做访谈式决策,每条消息一个问题,顺序为范式、受众(内部/伙伴/公开/混合)、现状(全新、单个未版本化、已有多版本)、破坏性变更压力、消费者可达性、截止日期、一次性或长期、投入上限。据受众设定通知期:全公开至少 12 个月,涉及移动应用或企业客户升至至少 24 个月,伙伴写入合同或 SLA,内部用消费者驱动契约测试与协同部署替代通知期;并发活跃版本上限 2–3 个。沟通分阶段:宣布、弃用(两版并行)、日落、移除;先发 Deprecation 头(RFC 9745),日期确定后加 Sunset 头(RFC 8594)与 Link rel="successor-version"(RFC 8288),并在 OpenAPI 标注 deprecated: true,同时配合更新日志、控制台横幅、定向邮件或响应内警告等人类渠道。执行应避免未版本化回退路径。
限制:资料未提供收费、价格与平台信息;部分基准与案例为外部引用,需自行核对;文档建议将外部基准表述为“至少 X 个月”。