Skip to content
Server Plugin

Ktor Server 中的 Server-Sent Events

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

代码示例: server-sse

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

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

要详细了解面向客户端支持的 SSE 插件,请参阅 SSE 客户端插件SSE 插件允许客户端通过 HTTP 连接从服务器接收基于事件的更新。。

对于多向通信,请考虑使用 WebSocketsWebSockets 插件允许你在服务器与客户端之间创建多路通信会话。。它们使用 WebSocket 协议在服务器与客户端之间提供全双工通信。

限制

Ktor 不提供对 SSE 响应数据压缩的支持。 如果您使用 Compression所需依赖项: io.ktor:ktor-server-compression 插件,它在默认情况下将跳过对 SSE 响应的压缩。

添加依赖项

要使用 SSE,请将 ktor-server-sse 工件添加到您的构建脚本中:

kotlin
implementation(ktorLibs.server.sse)
上述代码片段使用 Ktor 版本型录(Version Catalog)来指定 Ktor 依赖项。
groovy
implementation ktorLibs.server.sse
上述代码片段使用 Ktor 版本型录(Version Catalog)来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-sse-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

安装 SSE

要在您的应用程序中安装 SSE 插件,请将其传递给指定模块模块允许您通过对路由进行分组来构建应用程序结构。中的 install 函数。以下示例展示了如何安装 SSE:

  • 在 embeddedServer() 函数调用中。
  • 在 Application 类上显式定义的 module() 扩展函数中。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.sse.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(SSE)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.sse.*
// ...
fun Application.module() {
    install(SSE)
    // ...
}

处理 SSE 会话

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

  1. 指定特定 URL 路径:

    kotlin
    routing {
        sse(&quot;/events&quot;) {
            // send events to clients
        }
    }
  2. 不指定路径:

    kotlin
    routing {
        sse {
            // send events to clients
        }
    }

SSE 会话块

在 sse 块中,您可以定义指定路径的处理程序,由 ServerSSESession 类表示。块内提供以下函数和属性:

send()
创建并向客户端发送一个 ServerSentEvent。
call
发起该会话的关联接收项 ApplicationCall。
close()
关闭会话并终止与客户端的连接。当所有 send() 操作完成时,close() 方法会被自动调用。
使用 close() 函数关闭会话不会向客户端发送终止事件。若要在关闭会话前指示 SSE 流的结束,请使用 send() 函数发送特定事件。

示例:处理单个会话

以下示例演示了如何在 /events 端点上设置 SSE 会话,并通过 SSE 通道发送 6 个独立的事件,每个事件之间间隔 1 秒(1000 毫秒):

kotlin
routing {
    sse("/events") {
        repeat(6) {
            send(ServerSentEvent("this is SSE #$it"))
            delay(1000)
        }
    }
}

有关完整示例,请参阅 server-sse。

SSE 心跳

心跳通过定期发送事件来确保 SSE 连接在空闲期间保持活动状态。只要会话保持活动,服务器就会按配置的间隔发送指定的事件。

要启用并配置心跳,请在 SSE 路由处理程序中使用 .heartbeat() 函数:

kotlin
sse("/heartbeat") {
    heartbeat {
        period = 10.milliseconds
        event = ServerSentEvent("heartbeat")
    }
    // ...
}

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

您还可以使用 eventProvider 属性动态生成心跳事件:

kotlin
sse("/heartbeat-custom") {
    heartbeat {
        period = 30.milliseconds
        eventProvider = {
            ServerSentEvent(data = "ts=${Clock.System.now()}")
        }
    }
    // ...
}

设置后,每次检测信号触发时都会调用 eventProvider 来生成一个 ServerSentEvent。这使得心跳事件能够包含动态内容,例如时间戳或状态信息。

如果同时配置了 event 和 eventProvider,则 eventProvider 优先于 event。

序列化

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

kotlin
@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)

@Serializable
data class Product(val id: Int, val prices: List<Int>)

fun Application.module() {
    install(SSE)

    routing {
        // example with serialization
        sse("/json", serialize = { typeInfo, it ->
            val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
            Json.encodeToString(serializer, it)
        }) {
            send(Customer(0, "Jet", "Brains"))
            send(Product(0, listOf(100, 200)))
        }
    }
}

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

有关完整示例,请参阅 server-sse。