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 構件新增至您的組建指令碼中:
implementation(ktorLibs.server.websockets)implementation ktorLibs.server.websockets<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-websockets-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>安裝 WebSockets
若要在您的應用程式中安裝 WebSockets 外掛程式,請在指定的 模組模組可讓您透過對路由進行分組來建構應用程式。 中將其傳遞給 install 函式。 以下範例示範如何安裝 WebSockets:
- 在
embeddedServer()函式呼叫中。 - 在
Application類別上明確定義的module()擴充函式中。
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)
}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屬性設定用於序列化/反序列化的轉換器。
install(WebSockets) {
pingPeriod = 15.seconds
timeout = 15.seconds
maxFrameSize = Long.MAX_VALUE
masking = false
}處理 WebSockets 工作階段
API 概觀
安裝並設定好 WebSockets 外掛程式後,您即可定義端點來處理 WebSocket 工作階段。若要在伺服器上定義 WebSocket 端點,請在 routing 區塊內呼叫 webSocket 函式:
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 端點以處理與單一用戶端的工作階段:
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 通訊提供了一種具擴充性且並行友善的方法。以下是實作此模式的方式:
- 定義用於廣播訊息的
SharedFlow:
val messageResponseFlow = MutableSharedFlow<MessageResponse>()
val sharedFlow = messageResponseFlow.asSharedFlow()- 在您的 WebSocket 路由中,實作廣播與訊息處理邏輯:
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 還是其他例外狀況)才會跳出無限迴圈:
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()
}
}