Skip to content
Server Plugin

Ktor Server 中的 Server-Sent Events

必要相依性:io.ktor:ktor-server-sse

程式碼範例: server-sse

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

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

若要進一步了解用戶端支援的 SSE 外掛程式,請參閱 SSE 用戶端外掛程式SSE 外掛程式允許用戶端透過 HTTP 連線從伺服器接收以事件為基礎的更新。。

如需多向通訊,請考慮使用 WebSocketsWebsockets 外掛程式允許您在伺服器與用戶端之間建立多向通訊工作階段。。它們使用 WebSocket 通訊協定在伺服器與用戶端之間提供全雙工通訊。

限制

Ktor 不支援 SSE 回應的資料壓縮。如果你使用 Compression必要相依性: io.ktor:ktor-server-compression 外掛程式,它預設會跳過 SSE 回應的壓縮。

新增相依性

若要使用 SSE,請將 ktor-server-sse 構件新增至你的組建指令碼中:

kotlin
implementation(ktorLibs.server.sse)
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
groovy
implementation ktorLibs.server.sse
上述程式碼片段使用 Ktor version catalog 來指定 Ktor 相依性。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-server-sse-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

安裝 SSE

若要在應用程式中安裝 SSE 外掛程式,請將其傳遞給指定模組模組可讓您透過對路由進行分組來建構應用程式。中的 install 函式。以下範例展示如何安裝 SSE:

  • 在 embeddedServer() 函式呼叫中。
  • 在 Application 類別上明確定義的 module() 擴充函式中。
kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.sse.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        install(SSE)
        // ...
    }.start(wait = true)
}
kotlin
import io.ktor.server.application.*
import io.ktor.server.sse.*
// ...
fun Application.module() {
    install(SSE)
    // ...
}

處理 SSE 工作階段

安裝 SSE 外掛程式後,你可以新增一個路由來處理 SSE 工作階段。為此,請在 routing 區塊內呼叫 sse() 函式。有兩種設定 SSE 路由的方式:

  1. 指定特定 URL 路徑:

    kotlin
    routing {
        sse(&quot;/events&quot;) {
            // send events to clients
        }
    }
  2. 不指定路徑:

    kotlin
    routing {
        sse {
            // send events to clients
        }
    }

SSE 工作階段區塊

在 sse 區塊內,你可以為指定的路徑定義處理常式,該區塊由 ServerSSESession 類別表示。區塊內提供以下函式與屬性:

send()
建立並向用戶端傳送 ServerSentEvent。
call
發起該工作階段所接收到的關聯 ApplicationCall。
close()
關閉工作階段並終止與用戶端的連線。當所有 send() 操作完成時,會自動呼叫 close() 方法。
使用 close() 函式關閉工作階段不會向用戶端傳送終止事件。若要在關閉工作階段前指示 SSE 串流結束,請使用 send() 函式傳送特定事件。

範例:處理單一工作階段

以下範例示範如何在 /events 端點上設定 SSE 工作階段,透過 SSE 通道傳送 6 個獨立事件,每個事件之間間隔 1 秒(1000 毫秒):

kotlin
routing {
    sse("/events") {
        repeat(6) {
            send(ServerSentEvent("this is SSE #$it"))
            delay(1000)
        }
    }
}

完整範例請參閱 server-sse。

SSE 心跳機制 (Heartbeat)

心跳機制可透過定期傳送事件,確保 SSE 連線在閒置期間保持活動狀態。只要工作階段保持作用中,伺服器就會按照設定的間隔傳送指定事件。

若要啟用並設定心跳機制,請在 SSE 路由處理常式內使用 .heartbeat() 函式:

kotlin
sse("/heartbeat") {
    heartbeat {
        period = 10.milliseconds
        event = ServerSentEvent("heartbeat")
    }
    // ...
}

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

你也可以使用 eventProvider 屬性動態產生心跳事件:

kotlin
sse("/heartbeat-custom") {
    heartbeat {
        period = 30.milliseconds
        eventProvider = {
            ServerSentEvent(data = "ts=${Clock.System.now()}")
        }
    }
    // ...
}

設定後,每次心跳觸發時都會叫用 eventProvider 來產生 ServerSentEvent。這使得心跳事件能夠包含動態內容,例如時間戳記或狀態資訊。

如果同時設定了 event 和 eventProvider,則 eventProvider 的優先順序高於 event。

序列化

若要啟用序列化,請在 SSE 路由上使用 serialize 參數提供自訂序列化函式。在處理常式內部,你可以使用 ServerSSESessionWithSerialization 類別來傳送序列化事件:

kotlin
@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)

@Serializable
data class Product(val id: Int, val prices: List<Int>)

fun Application.module() {
    install(SSE)

    routing {
        // example with serialization
        sse("/json", serialize = { typeInfo, it ->
            val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
            Json.encodeToString(serializer, it)
        }) {
            send(Customer(0, "Jet", "Brains"))
            send(Product(0, listOf(100, 200)))
        }
    }
}

此範例中的 serialize 函式負責將資料物件轉換為 JSON,接著放入 ServerSentEvent 的 data 欄位中。

完整範例請參閱 server-sse。