Server-Sent Events

Client Plugin

Ktor Client 中的 Server-Sent Events

代码示例： client-sse

Server-Sent Events (SSE) 是一项允许服务器通过 HTTP 连接持续向客户端推送事件的技术。它在服务器需要发送基于事件的更新而无需客户端反复轮询服务器的情况下特别有用。

Ktor 支持的 SSE 插件提供了一种在服务器和客户端之间创建单向连接的简便方法。

TIP

要了解更多关于服务器端支持的 SSE 插件的信息，请参阅

SSE 服务器插件

SSE 插件允许服务器通过 HTTP 连接向客户端发送基于事件的更新。

。

添加依赖项

SSE 仅需要

ktor-client-core

了解如何向现有项目添加客户端依赖项。

构件，不需要任何特定的依赖项。

安装 SSE

要安装 SSE 插件，请在 客户端配置块 内将其传递给 install 函数：

配置 SSE 插件

您可以选择在 install 块中通过设置 SSEConfig 类支持的属性来配置 SSE 插件。

SSE 重连

要启用自动重连，请将 maxReconnectionAttempts 设置为大于 0 的值。您还可以使用 reconnectionTime 配置尝试之间的延迟：

如果与服务器的连接丢失，客户端将在尝试重连之前等待指定的 reconnectionTime。它将尝试最多 maxReconnectionAttempts 次来重新建立连接。

过滤事件

在以下示例中，SSE 插件安装到 HTTP 客户端，并配置为在传入流中包含仅包含注释的事件以及仅包含 retry 字段的事件：

响应缓冲

SSE 响应本质上是流式的，这使得捕获完整正文变得不切实际。您可以启用诊断缓冲区，以便在 SSE 流失败时安全地检索响应正文。缓冲区仅包含已处理的数据（不会从网络重新读取），旨在用于失败情况下的日志记录和错误分析。

您还可以按调用配置缓冲区：

缓冲策略

SSEBufferPolicy 类型提供了几种存储已处理 SSE 数据的策略。这些策略控制内存中保留多少流数据，并在发生错误时使其可用。

<code>Off</code>（默认）

不缓冲。

<code>LastLines(n)</code>

保留最后 n 行。

<code>LastEvent</code>

保留最后一个完成的 SSE 事件。

<code>LastEvents(n)</code>

保留最后 n 个完成的 SSE 事件。

<code>All</code>

保留到目前为止所有已处理的事件。

NOTE

对于长期存续的流，请谨慎使用。

失败时，您可以使用 response?.bodyAsText() 访问缓冲区，而无需从网络重新读取。

处理 SSE 会话

客户端的 SSE 会话由 ClientSSESession 接口表示。该接口公开了允许您接收来自服务器的服务器发送事件的 API。

访问 SSE 会话

HttpClient 允许您通过以下方式之一访问 SSE 会话：

• sse() 函数创建 SSE 会话并允许您对其执行操作。
• sseSession() 函数允许您打开一个 SSE 会话。

要指定 URL 端点，您可以从两个选项中进行选择：

• 使用 urlString 形参将整个 URL 指定为字符串。
• 分别使用 schema、host、port 和 path 形参来指定协议方案、域名、端口号和路径名。

NOTE

ClientSSESession 和 ClientSSESessionWithDeserialization 实例仅在会话期间有效。当 serverSentEvents { ... } 块完成或连接关闭时，它们的作用域会自动取消。

此外，还有以下形参可用于配置连接：

<code>reconnectionTime</code>

设置重连延迟。

<code>showCommentEvents</code>

指定是否在传入流中显示仅包含注释的事件。

<code>showRetryEvents</code>

指定是否在传入流中显示仅包含 retry 字段的事件。

<code>deserialize</code>

一个反序列化函数，用于将 TypedServerSentEvent 的 data 字段转换为对象。更多信息请参阅 反序列化。

SSE 会话块

在 lambda 实参中，您可以访问 ClientSSESession 上下文。该块中提供以下属性：

<code>call</code>

发起会话的相关 HttpClientCall。

<code>incoming</code>

传入的服务器发送事件流。

下面的示例创建了一个具有 events 端点的新 SSE 会话，通过 incoming 属性读取事件并打印接收到的 ServerSentEvent。

有关完整示例，请参阅 client-sse。

反序列化

SSE 插件支持将服务器发送事件反序列化为类型安全的 Kotlin 对象。当处理来自服务器的结构化数据时，此功能特别有用。

要启用反序列化，请在 SSE 访问函数上使用 deserialize 形参提供自定义反序列化函数，并使用 ClientSSESessionWithDeserialization 类来处理反序列化后的事件。

以下是使用 kotlinx.serialization 反序列化 JSON 数据的示例：

有关完整示例，请参阅 client-sse。