用途:当字段、操作或资源需要重命名或移除,且消费方需要迁移时间时,用本技能规划 API 演进;也用于向客户端公告移除日期,或在弃用与并行 /v1、/v2 之间做取舍,以及处理弃用与分组无法表达的破坏性表示变更。
主要能力:优先采用弃用方案,在资源、操作或 #[ApiProperty] 上设置 deprecationReason;添加带日期的 sunset,并在 v4 上附加携带 Deprecation(RFC 9745)的响应头以及 rel="successor-version" 的 Link。v4 之前需通过 KernelEvents::RESPONSE 监听器发出这些响应头。若仍属破坏性变更,可暴露并行的 uriTemplate(/v1、/v2)并配以不同分组,或使用每个版本一个 provider 的输出 DTO。还需在 OpenAPI 中把旧操作标记为已弃用、按版本记录变更,并测试每个仍活跃的版本。
使用方式:按默认工作流先尝试弃用,再补 sunset 与响应头,最后才考虑并行路径或 DTO。
限制与注意:路径版本化是后备而非默认;始终设置 sunset 日期,活跃版本最多保留 2 到 3 个;deprecationReason 与 sunset 在 v3、v4 稳定,但 RFC 9745 响应头选项属 v4 时代,需在已安装版本上验证;次要的增量变更应使用分组而非新版本。输出契约包括所选弃用或版本化策略及理由、被弃用元素及其 sunset 日期与后继链接、每个活跃版本与响应头的测试。
资料未提供具体安装命令、代码示例与价格信息。