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 函数:
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 配置重试之间的延迟:
install(SSE) {
maxReconnectionAttempts = 4
reconnectionTime = 2.seconds
} 如果与服务器的连接丢失,客户端将在等待指定的 reconnectionTime 后尝试重新连接。它将最多进行指定次数的 maxReconnectionAttempts 尝试以重新建立连接。
筛选事件
在以下示例中,SSE 插件安装到了 HTTP 客户端中,并配置为在传入流中包含仅包含注释的事件以及仅包含 retry 字段的事件:
install(SSE) {
showCommentEvents()
showRetryEvents()
}处理 SSE 会话
客户端的 SSE 会话由 ClientSSESession 接口表示。该接口公开了允许您从服务器接收 server-sent events 的 API。
访问 SSE 会话
HttpClient 允许您通过以下方式之一访问 SSE 会话:
sse()函数会创建 SSE 会话并允许您对其进行操作。sseSession()函数允许您打开一个 SSE 会话。
要指定 URL 端点,您可以从以下两个选项中进行选择:
- 使用
urlString形参以字符串形式指定完整的 URL。 - 分别使用
schema、host、port和path形参来指定协议方案、域名、端口号和路径名称。
runBlocking {
client.sse(host = "127.0.0.1", port = 8080, path = "/events") {
// this: ClientSSESession
}
}ClientSSESession 和 ClientSSESessionWithDeserialization 实例仅在会话持续期间有效。当 serverSentEvents { ... } 块完成或连接关闭时,它们的作用域会自动取消。 此外,以下形参可用于配置连接:
reconnectionTimeshowCommentEventsshowRetryEventsretry 字段的事件。 deserializeTypedServerSentEvent 的 data 字段转换为对象的反序列化器函数。更多信息,请参阅反序列化。 SSE 会话块
在 lambda 实参中,您可以访问 ClientSSESession 上下文。该代码块内提供以下属性:
callHttpClientCall。 incoming 以下示例创建了一个连接到 events 端点的新 SSE 会话,通过 incoming 属性读取事件,并打印接收到的 ServerSentEvent。
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 数据的示例:
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。
