Server Plugin

Ktor Server 中的 Server-Sent Events

所需依赖项: io.ktor:ktor-server-sse

代码示例: server-sse

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

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

TIP

要了解有关用于客户端支持的 SSE 插件的更多信息，请参阅

SSE 客户端插件

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

。

NOTE

对于多向通信，请考虑使用

WebSockets

Websockets 插件允许您创建服务器与客户端之间的多向通信会话。

。它们使用 Websocket 协议在服务器和客户端之间提供全双工通信。

限制

Ktor 不支持 SSE 响应的数据压缩。 如果您使用

Compression

所需依赖项: io.ktor:ktor-server-sse 代码示例: server-sse 原生服务器支持: ✖️

插件，它将默认跳过 SSE 响应的压缩。

添加依赖项

要使用 SSE，您需要在构建脚本中包含 ktor-server-sse artifact：

Gradle (Kotlin)Gradle (Groovy)Maven

安装 SSE

要将 安装 SSE 插件到应用程序中， 请将其传递给指定

模块

模块允许您通过分组路由来构建应用程序。

中的 install 函数。 以下代码片段展示了如何安装 SSE ...

• ... 在 embeddedServer 函数调用内部。
• ... 在显式定义的 module 内部，它是 Application 类的一个扩展函数。

embeddedServermodule

处理 SSE 会话

安装 SSE 插件后，您可以添加一个路由来处理 SSE 会话。 为此，请在 路由 代码块内调用 sse() 函数。设置 SSE 路由有两种方式：

1. 使用特定的 URL 路径：

2. 不带路径：

SSE 会话代码块

在 sse 代码块中，您定义了指定路径的处理程序，它由 ServerSSESession 类表示。以下函数和属性在该代码块中可用：

send()

创建并向客户端发送一个 ServerSentEvent。

call

关联的已接收 ApplicationCall，它发起了该会话。

close()

关闭会话并终止与客户端的连接。当所有 send() 操作完成后，close() 方法会自动调用。

NOTE

使用 close() 函数关闭会话不会向客户端发送终止事件。要在关闭会话前指示 SSE 流的结束，请使用 send() 函数发送一个特定事件。

示例：处理单个会话

以下示例演示了如何在 /events 端点上设置 SSE 会话，通过 SSE 通道发送 6 个独立事件，每个事件之间有 1 秒（1000 毫秒）的延迟：

有关完整示例，请参见 server-sse。

SSE 心跳

心跳通过周期性发送事件，确保 SSE 连接在不活动期间保持活跃。只要会话保持活跃，服务器将按配置的间隔发送指定事件。

要启用和配置心跳，请在 SSE 路由处理程序内使用 .heartbeat() 函数：

在此示例中，心跳事件每 10 毫秒发送一次，以维持连接。

序列化

要启用序列化，请在 SSE 路由上使用 serialize 形参提供一个自定义序列化函数。在处理程序内部，您可以使用 ServerSSESessionWithSerialization 类来发送序列化事件：

在此示例中，serialize 函数负责将数据对象转换为 JSON，然后将其放置在 ServerSentEvent 的 data 字段中。

有关完整示例，请参见 server-sse。