公开异步系统的公共 API

Posted 2023-03-28

【中文标题】公开异步系统的公共 API

【英文标题】：Expose public API for async system

【发布时间】：2021-12-02 18:18:18

【问题描述】：

我们现在正致力于向外部世界公开我们的生产 Rest API，以便将不同的 3rd 方集成到我们的系统中。 我们遇到的问题之一是，由于高规模和性能的原因，许多API 命令都是异步处理的，因此无法将结果直接返回给调用者。

例如 - deliver order 命令可能需要一些时间才能完成，这意味着：

在响应正文中，我们无法返回传递文件​​，因为它们尚未处理，但只有 202 accepted 状态。 我们不能保证在下次致电 get deliveries API 时这些都准备好了。

对于如何解决这个异步问题，我们几乎没有什么想法，但我们想知道是否有一些用于异步系统公开 API 的最佳实践。其中大多数是 202 状态码，或者可能是 command ID，它们可以轮询/注册到 webhook，这似乎很潮。

使用这些 API 的客户是否可以理解他们执行的操作需要时间才能发生？并且同步响应并不总是可用？

【问题讨论】：

大概开始整个流程的操作会返回一个标识符，以后可以用来查询整个流程的状态？

是的，这是一个选项 - 我将其称为 command ID。问题是它是否是我们的系统和它的客户端之间的一个良好且方便的接口。

【参考方案1】：

有一些易于理解的模式用于通过 HTTP API 公开长时间运行的异步操作。你如何去做取决于你的具体要求，这里有一些注意事项：

短轮询。在此模式中，您有一个“启动”HTTP API，它返回 HTTP 202 和异步操作的唯一标识符。然后，您有一个“查询”HTTP API，它接受该唯一标识符并以操作状态进行响应。由调用者决定调用“查询”API 的频率，但一般来说，在异步操作完成和调用者发现它的那一刻之间会有延迟。这种模式的一个例子是 AWS 的 Cloud Watch Logs Insigts StartQuery 和 GetQueryResults API。

长轮询。在此模式中，“查询”HTTP API 是一个 HTTP 长轮询，这意味着服务器将保持打开状态，直到操作完成或经过最长时间（通常少于 45 秒）。如果 HTTP 长轮询在异步操作完成之前返回，调用者应该立即发出一个新的“查询”操作。这种模式通常对您来说实现起来更复杂，并且更占用资源（保持 TCP 连接打开），但会降低调用者发现操作竞争的延迟。

网络套接字。在此模式中，调用者创建一个持久的 webhook 连接来启动异步操作并等待其完成。这在通知调用者完成时提供了最低的延迟，但超出了常规 HTTP 的 RPC 语义的“面包和黄油”，因此需要调用者方面更复杂一些。

网络钩子。一些系统选择公开 webhook 以通知客户异步发生的重要事件。根据您的异步操作的持续时间，这可能是使用正确的模式。例如，Stripe uses webhooks a lot 通知客户付款状态的变化。

除了处理异步操作，there is a number of other considerations when exposing HTTP APIs from your system 的想法是帮助人们与您的应用程序集成。