Server-Sent Events

Client Plugin

Ktor Client 中的 Server-Sent Events

程式碼範例： client-sse

Server-Sent Events (SSE) 是一種允許伺服器透過 HTTP 連線持續將事件推送到用戶端的技術。當伺服器需要發送基於事件的更新而不需要用戶端重複輪詢伺服器時，這項技術特別有用。

Ktor 支援的 SSE 外掛程式提供了一種簡單的方法，用於在伺服器和用戶端之間建立單向連線。

TIP

若要進一步了解用於伺服器端支援的 SSE 外掛程式，請參閱

SSE 伺服器外掛程式

SSE 外掛程式允許伺服器透過 HTTP 連線向用戶端發送基於事件的更新。

。

新增相依性

SSE 僅需要

ktor-client-core

了解如何向現有專案新增用戶端相依性。

構件，不需要任何特定的相依性。

安裝 SSE

要安裝 SSE 外掛程式，請將其傳遞給 用戶端配置區塊 內的 install 函式：

配置 SSE 外掛程式

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

SSE 重新連線

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

如果與伺服器的連線中斷，用戶端將在嘗試重新連線之前等待指定的 reconnectionTime。它最多會進行 指定的 maxReconnectionAttempts 次嘗試來重新建立連線。

篩選事件

在以下範例中，SSE 外掛程式已安裝到 HTTP 用戶端中，並配置為在傳入流中僅包含包含註解的事件，以及僅包含 retry 欄位的事件：

回應緩衝

SSE 回應在本質上是流式的，這使得擷取完整內容主體並不切實際。您可以啟用診斷緩衝區，以便在 SSE 流失敗時安全地檢索回應主體。該緩衝區僅包含已經處理過的資料（不從網路重新讀取），旨在用於失敗情況下的記錄和錯誤分析。

您也可以針對每次呼叫進行配置：

緩衝策略

SSEBufferPolicy 型別提供了幾種儲存已處理 SSE 資料的策略。這些策略控制了流中有多少內容保留在記憶體中，並在發生錯誤時可供使用。

<code>Off</code>（預設）

不進行緩衝。

<code>LastLines(n)</code>

保留最後 n 行。

<code>LastEvent</code>

保留最後一個完成的 SSE 事件。

<code>LastEvents(n)</code>

保留最後 n 個完成的 SSE 事件。

<code>All</code>

保留目前為止所有已處理的事件。

NOTE

對於長效流，請謹慎使用。

發生失敗時，您可以使用 response?.bodyAsText() 存取緩衝區，而無需從網路重新讀取。

處理 SSE 工作階段

用戶端的 SSE 工作階段由 ClientSSESession 介面表示。此介面公開了允許您從伺服器接收伺服器傳送事件的 API。

存取 SSE 工作階段

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

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

要指定 URL 端點，您可以從兩個選項中進行選擇：

• 使用 urlString 參數將整個 URL 指定為字串。
• 分別使用 schema、host、port 和 path 參數來指定協定架構、網域名稱、連接埠號和路徑名稱。

NOTE

ClientSSESession 和 ClientSSESessionWithDeserialization 執行個體僅在工作階段持續期間有效。當 serverSentEvents { ... } 區塊完成或連線關閉時，其作用域會自動取消。

此外，還有以下參數可用於配置連線：

<code>reconnectionTime</code>

設定重新連線延遲。

<code>showCommentEvents</code>

指定是否在傳入流中顯示僅包含註解的事件。

<code>showRetryEvents</code>

指定是否在傳入流中顯示僅包含 retry 欄位的事件。

<code>deserialize</code>

一個反序列化函式，用於將 TypedServerSentEvent 的 data 欄位轉換為物件。如需更多資訊，請參閱 反序列化。

SSE 工作階段區塊

在 Lambda 引數內，您可以存取 ClientSSESession 內容。區塊內提供以下屬性：

<code>call</code>

發起該工作階段的關聯 HttpClientCall。

<code>incoming</code>

一個傳入的伺服器傳送事件流。

下面的範例建立了一個連接到 events 端點的新 SSE 工作階段，透過 incoming 屬性讀取事件，並列印接收到的 ServerSentEvent 。

如需完整範例，請參閱 client-sse。

反序列化

SSE 外掛程式支援將伺服器傳送事件反序列化為型別安全的 Kotlin 物件。此功能在處理來自伺服器的結構化資料時特別有用。

要啟用反序列化，請在 SSE 存取函式上使用 deserialize 參數提供自訂的反序列化函式，並使用 ClientSSESessionWithDeserialization 類別來處理反序列化後的事件。

這是一個使用 kotlinx.serialization 反序列化 JSON 資料的範例：

如需完整範例，請參閱 client-sse。