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 设置,例如帧大小、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 属性指定是否启用掩码。
  • 使用 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 或关闭帧等控制帧。 要处理控制帧并重新组装分片帧,请使用 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,然后由其广播给所有收集器。

通过使用此模式,你可以高效管理多个 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()
    }
}