Client Plugin

Ktor Client 中的 Server-Sent Events

代码示例: client-sse

Server-Sent Events (SSE) 是一种技术，允许服务器通过 HTTP 连接持续推送事件到客户端。在服务器需要发送基于事件的更新而无需客户端重复轮询服务器的场景中，它尤其有用。

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

TIP

关于 SSE 插件服务器端支持的更多信息，请参见

SSE 服务器插件

The SSE plugin allows a server to send event-based updates to a client over an HTTP connection.

。

添加依赖项

SSE 仅需要

ktor-client-core

Learn how to add client dependencies to an existing project.

artifact，并且不需要任何特定依赖项。

安装 SSE

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

配置 SSE 插件

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

SSE 重新连接

️️不支持：OkHttp

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

如果与服务器的连接丢失，客户端将等待指定的 reconnectionTime，然后尝试重新连接。它将最多进行 指定的 maxReconnectionAttempts 次尝试以重新建立连接。

过滤事件

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

处理 SSE 会话

客户端的 SSE 会话由 ClientSSESession 接口表示。此接口暴露了允许您从服务器接收 Server-Sent Events 的 API。

访问 SSE 会话

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

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

要指定 URL 端点，您有两种选择：

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

可选地，以下形参可用于配置连接：

reconnectionTime

设置重新连接延迟。

showCommentEvents

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

showRetryEvents

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

deserialize

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

SSE 会话代码块

在 lambda 实参中，您可以访问 ClientSSESession 上下文。代码块中可用以下属性：

call

发起会话的关联 HttpClientCall。

incoming

传入的 Server-Sent Events 流。

以下示例使用 events 端点创建新的 SSE 会话，通过 incoming 属性读取事件并打印接收到的 ServerSentEvent 。

关于完整示例，请参见 client-sse。

反序列化

SSE 插件支持将 Server-Sent Events 反序列化为类型安全的 Kotlin 对象。当处理来自服务器的结构化数据时，此特性尤其有用。

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

这是一个使用 kotlinx.serialization 反序列化 JSON 数据的示例：

关于完整示例，请参见 client-sse。