摘要

  • RFC 9727 规定了 /.well-known/api-catalog 和 api-catalog 链接关系，让发布者可以机器可读地声明一组 API；它没有为每个条目的归属、授权、可达性、监控或健康背书。
  • 首级目录、跨域目录和嵌套目录各有自己的发布权威、上下文、缓存与更新时间。目录扩大了地图，也扩大了必须保留的证据边界。
  • 从目录删除一个 item，只能证明发布内容发生变化。接口是否真正退役，还要连接暴露、流量、依赖、变更执行、回滚和撤回后的观察。

一张整齐的目录，可以对应一片凌乱的资产

RFC 9727 于 2025 年 2 月作为 IETF 标准轨文档发布。它给出两个很小却实用的机制：api-catalog 链接关系，以及 /.well-known/api-catalog。发布者可以在这个 well-known 地址响应 GET，也可以通过 Link 响应头指向目录；目录采用 Linkset JSON，用 item 关系列出 API，用 api-catalog 关系连接下级目录。

这解决的是发现问题。API 资产过去常散落在部署文件、网关配置、开发者门户和个人表格中。标准入口让发布者可以公开一份结构化声明，第三方工具也能自动读取。可是“声明”不能被悄悄改写成“事实全集”。

Web Linking 表达的是带类型的关系。一个语法正确的 item，不证明目标域名从某个网络可解析，不证明端口正在监听，不证明凭据存在，不证明目录发布者拥有目标系统，更不证明一笔业务交易能够完成。反过来也一样：一个监听中的接口不会因为没有出现在目录里就消失。

OWASP API9:2023 把旧版本、未记录主机和环境不清列为资产管理风险。RFC 9727 可以减少这种盲区；如果组织只统计目录链接，它也可能制造一种更整洁的盲区——地图已经更新，资产却没有跟上。

权威要逐条边来判断

最简单的目录由发布者自己的域名托管。即使如此，目录里的每个目标也不必属于发布者。它可能是合作方服务、托管平台、区域端点，甚至只是为了兼容而保留的历史入口。目录能证明的是：发布者在某个时间选择声明这条关系。目标由谁运行、谁有权更改，仍需独立记录。

RFC 9727 允许无法托管 well-known 资源的发布者，指向另一个域名上的目录。这个设计解决实际部署限制，却不会把外部域名变成普遍权威。发现响应、重定向链、两端 TLS 身份、时间戳和目录内容哈希，合起来才是一条可审查的发布链。链条发生变化时，不能只因页面标题相同就假设权威连续。

嵌套目录把问题递归放大。集团目录可能指向产品目录，产品目录再指向各地区目录；每一跳都可能有不同维护者、发布节奏和访问边界。RFC 9264 要求明确 link context，正是因为脱离 anchor 搬运 Linkset 会改变链接的含义。目录结构不是一棵自动继承真相的树，而是一张由有日期的声明组成的图。

因此，一份可用的“目录回执”至少要保存响应域名、发现路径、重定向、TLS 对端、响应时间、媒体类型、profile、ETag 或 Last-Modified、正文哈希，以及每个明确的 context—target—relation 三元组。首次和末次观察只能叫观察，不能偷换成创建和删除日期。以上是本文提出的治理做法，不是 RFC 9727 新增的规范要求。

目录按缓存时钟运行，API 按业务时钟运行

RFC 9111 区分新鲜度、重新验证和陈旧响应。ETag 可以证明两次验证之间表示没有变化，却不能证明其中每个 API 一直在运行。较长的新鲜期提高发现效率，也可能延迟紧急删除的可见性；较短的新鲜期增加源站压力，却不会自动提高目录维护质量。

至少四个时间不能合并：发布者意图让目录生效的时间、源站实际返回的时间、缓存验证或复用的时间、运营者更改 API 或网关的时间。第五个时间属于观察者。“14:00 时目录中没有这个接口”只有在同时保存响应、缓存路径和观察时间时才可复核；它不等于“接口在 14:00 已关闭”。

RFC 9727 的运营章节已经承认维护成本：监控目录自身的可用性和性能，把目录访问与后续 API 请求做相关分析，删除陈旧条目，检查语法和业务规则，并把刷新纳入发布生命周期。它也明确表示目录是对 API 管理框架的补充，不是替代品。这条边界尤其重要。

目录健康不等于条目健康

探针可以成功获取目录、验证 Linkset JSON，并遍历全部下级目录，页面依然全绿；与此同时，一个 item 可能持续返回错误。反过来，目录源站可能故障，而早已保存地址的客户端仍能正常调用 API。

RFC 8631 注册了指向状态资源的 status 链接关系。状态页能提供另一种观察，却不会把目录、状态页和 API 合并成同一测量。健康证据必须说明交易、观察点、身份上下文和时间窗。TCP 连接成功、HTTP 返回成功和业务操作成功是三件不同的事。

这一区分也保护内部系统。RFC 9727 提醒目录可能泄露私有 API，因此建议使用 TLS、限制写权限、做安全与隐私审查、限流，并为内部目录配置适当访问控制。目录本身受保护，不代表其中某个接口没有意外暴露；目录公开，也不代表读者获得调用权。发现权限与端点暴露必须分别测量。

删除卡片，不会拔掉插口

RFC 9727 指出，对目录做审计有助于发现 zombie API，即无人支持、无人监控或无人修补的接口。它们之所以危险，正因为管理记录与运行系统已经分离。审计给出调查入口，不给出自动关停证明。

删除一个 item 只是发布事件。它可能是纠错、迁往另一个目录、暂时隐藏、替换或计划退役；它不会关闭监听器、撤销凭据、删除 DNS、排空队列，也不会升级未知客户端。目录继续保留条目，同样不能证明接口仍受支持。

退役回执需要把独立记录连接起来：保存最后一版目录快照和授权决定；记录 DNS、路由、负载均衡与网关变更；明确受影响的接口和环境；列出已知负责人、下游任务和数据流；说明流量观察窗及盲区；保存凭据和集成处理、执行确认、例外与回滚负责人，以及撤回后的探测。如果季度任务、缓存客户端或合作方网络不在测量范围内，就应写明“未知”，而不是填成零。

本文不再讲解 BTW 已有文章覆盖的 Deprecation 与 Sunset 客户端迁移边界。这里的结论更窄：从目录移除关系不是执行证据。服务器可能在移除后继续响应，也可能在链接仍存在时早已消失。证据系统要保留这种不一致，不能为了让报表好看而回写历史。

来源

规范与登记表：RFC 9727、RFC Editor 记录、IETF Datatracker、IANA well-known URI 登记表、IANA 链接关系登记表、RFC 9264、RFC 8288、RFC 8615、RFC 8631、RFC 9111、RFC 9745、RFC 8594、OWASP API9:2023。

注明归属的分析框架：Lu Heng—Note 64、运行代码优先、BTW 为何记录现实。