Skip to content
Server Plugin

Ktor Server 中的 WebSockets

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

程式碼範例: server-websockets

Native 伺服器Ktor 支援 Kotlin/Native,可讓您在無需額外執行階段或虛擬機的情況下執行伺服器。支援:✅

WebSocket 是一種在單一 TCP 連線上,為使用者的瀏覽器與伺服器之間提供全雙工通訊工作階段的協定。它特別適用於建立需要與伺服器來回傳輸即時資料的應用程式。

Ktor 在伺服器端與用戶端均支援 WebSocket 協定。

Ktor 允許您:

  • 設定基本 WebSocket 設定,例如訊框大小(frame size)、ping 週期等。
  • 處理用於在伺服器與用戶端之間交換訊息的 WebSocket 工作階段。
  • 新增 WebSocket 擴充套件。例如,您可以使用 Deflate 擴充套件,或實作自訂擴充套件。

若要了解用戶端的 WebSocket 支援,請參閱 WebSockets 用戶端外掛程式。

對於單向通訊工作階段,請考慮使用 Server-Sent Events (SSE)。SSE 特別適用於伺服器需要向用戶端傳送基於事件的更新之情況。

新增相依性 ​

若要使用 WebSockets,請將 ktor-server-websockets 構件新增至您的組建指令碼中:

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

安裝 WebSockets ​

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

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

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

設定 WebSockets ​

(選用)您可以透過在 install 區塊中傳入 WebSocketOptions 來設定外掛程式:

  • 使用 pingPeriod 屬性指定 ping 之間的時間間隔。
  • 使用 timeout 屬性設定逾時時間,超過該時間後將關閉連線。
  • 使用 maxFrameSize 屬性設定可接收或傳送的最大訊框大小。
  • 使用 masking 屬性指定是否啟用遮罩 (masking)。
  • 使用 contentConverter 屬性設定用於序列化/反序列化的轉換器。
kotlin
install(WebSockets) {
    pingPeriod = 15.seconds
    timeout = 15.seconds
    maxFrameSize = Long.MAX_VALUE
    masking = false
}

處理 WebSockets 工作階段 ​

API 概觀 ​

安裝並設定好 WebSockets 外掛程式後,您即可定義端點來處理 WebSocket 工作階段。若要在伺服器上定義 WebSocket 端點,請在 routing 區塊內呼叫 webSocket 函式:

kotlin
routing { 
    webSocket("/echo") {
       // 處理 WebSocket 工作階段
    }
}

在此範例中,當使用預設設定時,伺服器會接受發送至 ws://localhost:8080/echo 的 WebSocket 請求。

在 webSocket 區塊內,您定義了 WebSocket 工作階段的處理常式,該工作階段由 DefaultWebSocketServerSession 類別表示。 該區塊內提供以下函式與屬性:

  • 使用 send 函式向用戶端傳送文字內容。
  • 使用 incoming 和 outgoing 屬性存取用於接收和傳送 WebSocket 訊框的通道。訊框由 Frame 類別表示。
  • 使用 close 函式傳送帶有指定原因的關閉訊框。

在處理工作階段時,您可以檢查訊框型別,例如:

  • Frame.Text 是文字訊框。對於此訊框型別,您可以使用 Frame.Text.readText() 讀取其內容。
  • Frame.Binary 是二進制訊框。對於此型別,您可以使用 Frame.Binary.readBytes() 讀取其內容。

請注意,incoming 通道不包含控制訊框(例如 ping/pong 或 close 訊框)。 若要處理控制訊框並重新重組分段訊框,請使用 webSocketRaw 函式來處理 WebSocket 工作階段。

若要取得有關用戶端的資訊(例如用戶端的 IP 位址),請使用 call 屬性。請參閱一般請求資訊。

下面我們將看看使用此 API 的範例。

範例:處理單一工作階段 ​

以下範例示範如何建立 echo WebSocket 端點以處理與單一用戶端的工作階段:

kotlin
routing {
    webSocket("/echo") {
        send("Please enter your name")
        for (frame in incoming) {
            frame as? Frame.Text ?: continue
            val receivedText = frame.readText()
            if (receivedText.equals("bye", ignoreCase = true)) {
                close(CloseReason(CloseReason.Codes.NORMAL, "Client said BYE"))
            } else {
                send(Frame.Text("Hi, $receivedText!"))
            }
        }
    }
}

如需完整範例,請參閱 server-websockets。

範例:處理多個工作階段 ​

為了有效管理多個 WebSocket 工作階段並處理廣播,您可以利用 Kotlin 的 SharedFlow。 這種方法為管理 WebSocket 通訊提供了一種具擴充性且並行友善的方法。以下是實作此模式的方式:

  1. 定義用於廣播訊息的 SharedFlow:
kotlin
val messageResponseFlow = MutableSharedFlow<MessageResponse>()
val sharedFlow = messageResponseFlow.asSharedFlow()
  1. 在您的 WebSocket 路由中,實作廣播與訊息處理邏輯:
kotlin

        webSocket("/ws") {
            send("You are connected to WebSocket!")

            val job = launch {
                sharedFlow.collect { message ->
                    send(message.message)
                }
            }

            runCatching {
                incoming.consumeEach { frame ->
                    if (frame is Frame.Text) {
                        val receivedText = frame.readText()
                        val messageResponse = MessageResponse(receivedText)
                        messageResponseFlow.emit(messageResponse)
                    }
                }
            }.onFailure { exception ->
                println("WebSocket exception: ${exception.localizedMessage}")
            }.also {
                job.cancel()
            }
        }

runCatching 區塊會處理傳入訊息並將其發射至 SharedFlow,隨後廣播給所有收集器 (collectors)。

透過使用此模式,您可以有效管理多個 WebSocket 工作階段,而無需手動追蹤個別連線。這種方法非常適合具有許多並行 WebSocket 連線的應用程式,並提供了一種簡潔、反應式的方式來處理訊息廣播。

如需完整範例,請參閱 server-websockets-sharedflow。

WebSocket API 與 Ktor ​

來自 WebSocket API 的標準事件 以下列方式對應至 Ktor:

  • onConnect 發生在區塊的開始處。
  • onMessage 發生在成功讀取訊息之後(例如透過 incoming.receive())或使用 for(frame in incoming) 進行掛起反覆運算之後。
  • onClose 發生在 incoming 通道關閉時。這會完成掛起反覆運算,或者在嘗試接收訊息時擲出 ClosedReceiveChannelException。
  • onError 相當於其他例外狀況。

在 onClose 和 onError 中,均會設定 closeReason 屬性。

在以下範例中,只有在發生例外狀況時(無論是 ClosedReceiveChannelException 還是其他例外狀況)才會跳出無限迴圈:

kotlin
webSocket("/echo") {
    println("onConnect")
    try {
        for (frame in incoming){
            val text = (frame as Frame.Text).readText()
            println("onMessage")
            received += text
            outgoing.send(Frame.Text(text))
        }
    } catch (e: ClosedReceiveChannelException) {
        println("onClose ${closeReason.await()}")
    } catch (e: Throwable) {
        println("onError ${closeReason.await()}")
        e.printStackTrace()
    }
}