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 外掛程式

您可以選擇透過設定 SSEConfig 類別所支援的屬性,在 install 區塊內配置 SSE 外掛程式。

SSE 重新連線

若要啟用自動重新連線,請將 maxReconnectionAttempts 設定為大於 0 的值。您也可以使用 reconnectionTime 來配置各次嘗試之間的延遲:

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

若與伺服器的連線中斷,用戶端將會等待指定的 reconnectionTime 後再嘗試重新連線。它最多會嘗試指定的 maxReconnectionAttempts 次數來重新建立連線。

篩選事件

在以下範例中,SSE 外掛程式已安裝至 HTTP 用戶端中,並配置為在傳入串流 (incoming flow) 中包含僅含有註解的事件,以及僅含有 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 介面表示。此介面公開了讓您能夠從伺服器接收伺服器發送事件的 API。

存取 SSE 工作階段

HttpClient 允許您透過以下方式之一存取 SSE 工作階段:

  • sse() 函式會建立 SSE 工作階段,並允許您對其進行操作。
  • sseSession() 函式允許您開啟一個 SSE 工作階段。

若要指定 URL 端點,您可以從兩個選項中進行選擇:

  • 使用 urlString 參數將整個 URL 指定為字串。
  • 分別使用 schema、host、port 和 path 參數來指定通訊協定配置 (scheme)、網域名稱、連接埠號碼與路徑名稱。
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
傳入的伺服器發送事件串流。

以下範例使用 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 外掛程式支援將伺服器發送事件反序列化為型別安全的 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。