摘要

  • 2025 年 3 月的 RFC 9745 定义了带 Structured Fields 日期的 Deprecation 响应字段。进入弃用状态后，资源仍可照常运行。
  • Link 的 deprecation 关系可指向迁移说明，甚至早于正式日期出现。2019 年的 RFC 8594 则用 Sunset 表示资源预期停止响应的时点。
  • 字段首先指向承载它的响应资源；若要覆盖整个 API，提供者须说明范围规则。需要有日期的真实响应记录，才能知道哪些服务实际采用了它。

正常响应里藏着一张退场通知

许多服务的终点从来不是突然宕机。接口继续返回数据，健康检查仍显示绿色，运营者却已决定以后不再推荐它。把公告只放在文档网站，读实际流量的客户端开发者未必看见；等到请求第一次失败才发通知，更不可能给业务留出迁移、测试和发版的时间。

RFC 9745 把通知带进 HTTP 响应。Deprecation 字段描述这条响应所标识的资源，值采用 Structured Fields 的日期写法。规范示例 Deprecation: @1688169599 指向 2023 年 6 月 30 日 23:59:59 UTC。未来日期表示届时进入弃用状态；过去日期表示已经进入。两种情况下，服务器都可以继续答复请求。

这正是新字段揭开的利益关系：同一份响应既交付成功结果，又告诉客户端不要再把未来建立在这条路径上。RFC 9745 明确说弃用行为本身不改变资源行为。当前可用和长期适宜是两回事。客户端团队若因为今天还能拿到数据而继续写新依赖，未来的拆迁工程只会更大。

通知的范围也不能凭想象扩大。字段默认针对承载它的响应资源。提供者可能想宣布整套 API 或一组端点的退场，但必须定义从某一资源的通知如何覆盖其他资源。只抓到一条响应的程序，知道的是这条响应的资源；整张退场地图仍由运营者的范围规则决定。

使用说明可以比日期先到

2025 年规范还登记了 deprecation 这一 Link 关系。提供者可以让响应指向弃用政策、替代资源或迁移说明。文档链接可以早于正式的 Deprecation 字段出现。此时客户端能读到运营者打算如何通知将来的弃用，但所请求的资源尚未进入弃用状态。先公开规则、再启动计时器，是标准允许的次序。

一个日期无法替开发者完成迁移。替代接口是否改变权限、数据形状和调用方式？旧版本会维持多久？这些问题需要可执行的说明。Link 让说明能从正在运行的接口被发现；说明是否完整、替代品是否可用，仍取决于提供者。标准把通知送到客户端面前，并没有替任何一方付工程费。

弃用时钟与关门时钟

2019 年 5 月的 RFC 8594 早已定义 Sunset，用 HTTP 日期表示资源预期停止响应的时点。Deprecation 讲的是另一刻：资源仍工作，但不再被推荐作为新依赖。前者的关注点是预期可用性终点，后者的关注点是继续投资的决定。把两个日期混成一张“关门通知”，会错过这段仍可平稳搬家的窗口。

RFC 9745 允许两个字段并列，且要求 Sunset 不得早于 Deprecation。示例把弃用放在 2023 年 6 月 30 日，把预期停止响应放在一年后。相反的顺序等于宣称服务会先关门、后宣布不推荐使用。字段写法也不同：Deprecation 用带 @ 的结构化日期，Sunset 保留传统 HTTP 日期。

两枚时钟都是提供者公布的规划信号。清楚的范围、能用的替代路径、与行动一致的时间安排，决定了它们对客户端有没有价值。若要知道 2025 年字段在何处落地，还缺具体服务的有日期响应记录。标准文本已经足以说明权力的分配：提供者在正常运行的接口里写下退场时间，客户端据此排队做搬迁工程。