Skip to content
Client Plugin

Ktor Client 中的 Server-Sent Events

代码示例: client-sse

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

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

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

添加依赖项

SSE 仅需要 ktor-client-core了解如何向现有项目添加客户端依赖项。 工件,不需要任何特定的依赖项。

安装 SSE

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

kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.sse.*

//...
val client = HttpClient(CIO) {
    install(SSE)
}

配置 SSE 插件

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

SSE 重新连接

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

kotlin
install(SSE) {
    maxReconnectionAttempts = 4
    reconnectionTime = 2.seconds
}

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

筛选事件

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

kotlin
install(SSE) {
    showCommentEvents()
    showRetryEvents()
}

响应缓冲

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

kotlin
install(SSE) {
    bufferPolicy = SSEBufferPolicy.LastEvents(10)
}

您还可以针对每次调用单独配置缓冲区:

kotlin
client.sse(url, {
    bufferPolicy(SSEBufferPolicy.All)
}) {
    // ...
}

缓冲策略

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

Off(默认)
不缓冲。
LastLines(n)
保留最后 n 行。
LastEvent
保留最后一个已完成的 SSE 事件。
LastEvents(n)
保留最后 n 个已完成的 SSE 事件。
All
保留目前为止所有已处理的事件。
对于长生命周期的流,请谨慎使用。

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

处理 SSE 会话

客户端的 SSE 会话由 ClientSSESession 接口表示。该接口公开了允许您从服务器接收 server-sent events 的 API。

访问 SSE 会话

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

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

要指定 URL 端点,您可以从以下两个选项中进行选择:

  • 使用 urlString 形参以字符串形式指定完整的 URL。
  • 分别使用 schema、host、port 和 path 形参来指定协议方案、域名、端口号和路径名称。
kotlin
runBlocking {
    client.sse(host = "127.0.0.1", port = 8080, path = "/events") {
        // this: ClientSSESession
    }
}
ClientSSESession 和 ClientSSESessionWithDeserialization 实例仅在会话持续期间有效。当 serverSentEvents { ... } 块完成或连接关闭时,它们的作用域会自动取消。

此外,以下形参可用于配置连接:

reconnectionTime
设置重连延迟。
showCommentEvents
指定是否在传入流中显示仅包含注释的事件。
showRetryEvents
指定是否在传入流中显示仅包含 retry 字段的事件。
deserialize
用于将 TypedServerSentEvent 的 data 字段转换为对象的反序列化器函数。更多信息,请参阅反序列化。

SSE 会话块

在 lambda 实参中,您可以访问 ClientSSESession 上下文。该代码块内提供以下属性:

call
发起该会话的相关 HttpClientCall。
incoming
传入的 server-sent events 流。

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

kotlin
fun main() {
    val client = HttpClient {
        install(SSE) {
            showCommentEvents()
            showRetryEvents()
        }
    }
    runBlocking {
        client.sse(host = "0.0.0.0", port = 8080, path = "/events") {
            while (true) {
                incoming.collect { event ->
                    println("Event from server:")
                    println(event)
                }
            }
        }
    }
}

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

反序列化

SSE 插件支持将 server-sent events 反序列化为类型安全的 Kotlin 对象。在处理来自服务器的结构化数据时,此功能特别有用。

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

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

kotlin
client.sse({
    url("http://localhost:8080/serverSentEvents")
}, deserialize = {
        typeInfo, jsonString ->
    val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
    Json.decodeFromString(serializer, jsonString)!!
}) { // `this` is `ClientSSESessionWithDeserialization`
    incoming.collect { event: TypedServerSentEvent<String> ->
        when (event.event) {
            "customer" -> {
                val customer: Customer? = deserialize<Customer>(event.data)
            }
            "product" -> {
                val product: Product? = deserialize<Product>(event.data)
            }
        }
    }
}

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