我可以弃用这个端点吗？

作者：Hannah Troisi

没有什么是永恒的，即使是设计得最好的 API。

让我们假设你是一个开发人员，接管了 Catalog 微服务的所有权。你被要求弃用/v1/catalog 端点而使用新的/v2/catalog 端点。你该怎么做呢？

无论移除的原因是什么——新版本还是计划的生命周期结束——优雅的 API 弃用的第一步是观察：

• 是否使用了这个端点？
• 如果是这样，是谁在召唤它？

是否使用了这个端点？

在弃用该端点之前，首先需要检查该端点是否正在实际使用。

搜索代码库

对于内部端点，一个很好的开始方法是在代码库中搜索对 API 的调用。然而，一旦你认为所有调用都被删除了，你仍然需要使用可观察性工具来验证所有 API 的使用确实已经停止。有可能你仍然从仍在运行的服务的旧版本获得流量。

请注意，在你从代码库中删除所有 API 调用之后，公司协议可能会要求你在关闭端点之前等待几个版本。大多数已建立的公司都有其微服务 API（甚至内部 API）的向后兼容性标准。例如，公司可能有一个策略，要求在 API 弃用和删除之间有 3 个版本，以防出现回滚。

使用可观察性工具进行验证

你公司用于确定端点使用情况的特定方法可能有所不同。一些应用程序导出它们在服务上显式定义的指标（例如 Prometheus）。有些应用程序设置为记录每个入站 HTTP 请求（例如 Apache 日志）。

另一个选择是使用Pixie[1]，这是 Kubernetes 应用程序的开源可观察性工具。Pixie使用 eBPF[2]自动跟踪多种协议[3]（HTTP、MySQL、gRPC 等）的请求流量。但是无论你如何收集数据，你都需要回答相同的问题。

让我们检查到/v1/catalog 端点的 HTTP 流量，看看是否有这个端点的任何客户端。

PxL 脚本的输出，显示发送到特定服务的所有 HTTP/2 流量。

端点与通配符？

现在你有了答案：实际上正在使用/v1/catalog 端点。

查看一下不同的请求路径，你可以看到端点包含一个通配符参数。在本例中，我们似乎有一个/v1/catalog/{uuid}/details 端点，它接受一个 uuid 查询参数，该参数将根据 API 客户机希望获得的产品的详细信息而改变。

通过逻辑端点进行集群提供了更好的 API 使用的高级视图。

例如，这两个调用:

/v1/catalog/d3588631-ad8e-49df-bbd6-3167f7efb291/details
/v1/catalog/d3234332-s5fe-s30s-gsh6-323434sdf634/details

应该被聚集到逻辑端点中：

/v1/catalog/*/details

让我们按逻辑端点对 Catalog 服务的请求进行集群。Pixie 采用了一种统计方法来解决这个问题，但是你也可以尝试使用 regex 手动构建模式。

PxL 脚本的输出，显示特定服务的所有端点，具有高延迟、错误和吞吐量统计信息。

Catalog 服务流量的这个高级视图确认有两个版本的/Catalog 端点接收流量，并且只有/v1 版本有/details 端点。

谁使用这个端点？

不幸的是，你的端点仍然在接收流量。如何确定来源，以便通知它们弃用？

检查请求头

让我们检查请求头以寻找线索。Pixie 自动跟踪完整的请求，包括正文和请求头。服务网格也可以在 Kubernetes 中捕获这类信息。

PxL 脚本的输出，显示到特定端点的所有 HTTP/2 流量（请求头以 JSON 形式展开）。

在这里，你可以看到请求头包括一个 Referer 和 API-Key 字段。将这些值聚合在一起，我们就得到了一个需要通知的 API 客户端的列表：

PxL 脚本的输出，列出了请求头'Referer'和'API-Key'字段的唯一值。

在请求头中找不到任何标识 API 客户端的信息？

这里有一些其他的地方可以检查：

• 请求体
• URL 参数
• 入站请求的 IP 地址

你确定的任何 API 客户端都应该在即将弃用时得到通知。如果某些客户机未能迁移到新的 API，则可以使用这种标识信息来实现渐进关闭，从而对客户机产生不同的影响。例如，免费层的客户端可能会稍微延迟他们弃用的 API 请求响应，而付费客户端可以继续使用弃用的 API 而不会受到任何惩罚。

开始弃用

现在你已经知道了使用 API 的情况，可以创建弃用计划了。

开发者不喜欢意外的弃用，所以最好以多种方式通知他们，包括：

• 文档：更新参考文档以防止新用户使用已弃用的 API。
• Slack/电邮通知：告诉现有用户如何以及何时迁移。
• 弃用/日落报头：为使用 HTTP 中间件的用户自动检测弃用的 API。
• 监控：跟踪端点流量，提醒 API 客户端进行迁移。
• 渐进关闭：给 API 客户端一个最后的警告。

一旦你尽了最大努力将剩余的客户端从已弃用的 API 中迁移出去，就该关闭端点了。消灭了技术债务！

对教程感兴趣？学习[4]如何运行这篇文章中包含的脚本。

参考资料

[1]Pixie: https://github.com/pixie-io/pixie

[2]使用 eBPF: https://docs.px.dev/about-pixie/pixie-ebpf/

[3]多种协议: https://docs.px.dev/about-pixie/data-sources/

[4]学习: https://github.com/pixie-io/pixie-demos/tree/main/endpoint-deprecation

[5]Slack: https://slackin.px.dev/