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 外掛程式
您可以選擇透過設定 SSEConfig 類別所支援的屬性,在 install 區塊內配置 SSE 外掛程式。
SSE 重新連線
若要啟用自動重新連線,請將 maxReconnectionAttempts 設定為大於 0 的值。您也可以使用 reconnectionTime 來配置各次嘗試之間的延遲:
install(SSE) {
maxReconnectionAttempts = 4
reconnectionTime = 2.seconds
} 若與伺服器的連線中斷,用戶端將會等待指定的 reconnectionTime 後再嘗試重新連線。它最多會嘗試指定的 maxReconnectionAttempts 次數來重新建立連線。
篩選事件
在以下範例中,SSE 外掛程式已安裝至 HTTP 用戶端中,並配置為在傳入串流 (incoming flow) 中包含僅含有註解的事件,以及僅含有 retry 欄位的事件:
install(SSE) {
showCommentEvents()
showRetryEvents()
}處理 SSE 工作階段
用戶端的 SSE 工作階段由 ClientSSESession 介面表示。此介面公開了讓您能夠從伺服器接收伺服器發送事件的 API。
存取 SSE 工作階段
HttpClient 允許您透過以下方式之一存取 SSE 工作階段:
sse()函式會建立 SSE 工作階段,並允許您對其進行操作。sseSession()函式允許您開啟一個 SSE 工作階段。
若要指定 URL 端點,您可以從兩個選項中進行選擇:
- 使用
urlString參數將整個 URL 指定為字串。 - 分別使用
schema、host、port和path參數來指定通訊協定配置 (scheme)、網域名稱、連接埠號碼與路徑名稱。
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 外掛程式支援將伺服器發送事件反序列化為型別安全的 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。
