Server Plugin

Ktor 伺服器中的伺服器傳送事件 (Server-Sent Events)

必要依賴項：io.ktor:ktor-server-sse

程式碼範例： server-sse

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

Ktor 支援的 SSE 插件提供了一種直接的方法，用於在伺服器和客戶端之間建立單向連線。

TIP

要了解更多關於客戶端支援的 SSE 插件，請參閱

SSE 客戶端插件

SSE 插件允許客戶端透過 HTTP 連線從伺服器接收基於事件的更新。

。

NOTE

對於多向通訊，請考慮使用

WebSockets

Websockets 插件允許您在伺服器和客戶端之間建立多向通訊會話。

。它們使用 Websocket 協定在伺服器和客戶端之間提供全雙工通訊。

限制

Ktor 不支援 SSE 回應的資料壓縮。 如果您使用

Compression

必要依賴項：io.ktor:ktor-server-sse 程式碼範例：server-sse 原生伺服器支援：✖️

插件，它將預設跳過 SSE 回應的壓縮。

新增依賴項

要使用 SSE，您需要在建置腳本中包含 ktor-server-sse 構件：

Gradle (Kotlin)Gradle (Groovy)Maven

安裝 SSE

要將 SSE 插件安裝到應用程式中，請將其傳遞給指定

模組

模組允許您透過分組路由來組織應用程式。

中的 install 函數。 下面的程式碼片段展示了如何安裝 SSE ...

• ... 在 embeddedServer 函數呼叫內部。
• ... 在明確定義的 module 內部，它是一個 Application 類別的擴充函數。

embeddedServermodule

處理 SSE 會話

安裝 SSE 插件後，您可以新增路由來處理 SSE 會話。 為此，請在 路由 區塊內部呼叫 sse() 函數。有兩種方式可以設定 SSE 路由：

1. 使用特定的 URL 路徑：

2. 不帶路徑：

SSE 會話區塊

在 sse 區塊中，您定義了指定路徑的處理器，該處理器由 ServerSSESession 類別表示。以下函數和屬性在此區塊中可用：

send()

建立並傳送 ServerSentEvent 到客戶端。

call

關聯的、發起此會話的已接收 ApplicationCall。

close()

關閉會話並終止與客戶端的連線。當所有 send() 操作完成後，close() 方法會自動呼叫。

NOTE

使用 close() 函數關閉會話不會向客戶端傳送終止事件。要在關閉會話前指示 SSE 流的結束，請使用 send() 函數傳送特定事件。

範例：處理單一會話

以下範例展示了如何在 /events 端點上設定一個 SSE 會話，透過 SSE 通道傳送 6 個獨立事件，每個事件之間延遲 1 秒 (1000 毫秒)：

有關完整範例，請參閱 server-sse。

SSE 心跳

心跳確保 SSE 連線在閒置期間透過定期傳送事件保持活躍。 只要會話保持活躍，伺服器就會以配置的間隔傳送指定事件。

要啟用和配置心跳，請在 SSE 路由處理器中呼叫 .heartbeat() 函數：

在此範例中，每 10 毫秒傳送一次心跳事件以維持連線。

序列化

要啟用序列化，請在 SSE 路由上使用 serialize 參數提供自訂序列化函數。 在處理器內部，您可以使用 ServerSSESessionWithSerialization 類別來傳送序列化事件：

此範例中的 serialize 函數負責將資料物件轉換為 JSON，然後將其放入 ServerSentEvent 的 data 欄位中。

有關完整範例，請參閱 server-sse。