WebSockets

Client Plugin

Ktor Client 中的 WebSockets

所需依赖：io.ktor:ktor-client-websockets

代码示例： client-websockets

WebSocket 是一种协议，它通过单个 TCP 连接在用户的浏览器和服务器之间提供全双工通信会话。它对于创建需要与服务器进行实时数据传输的应用程序特别有用。 Ktor 在服务器端和客户端都支持 WebSocket 协议。

客户端的 Websockets 插件允许您处理与服务器交换消息的 WebSocket 会话。

NOTE

并非所有引擎都支持 WebSockets。有关受支持引擎的概览，请参阅限制。

TIP

要了解服务器端的 WebSocket 支持，请参阅

Ktor Server 中的 WebSockets

Websockets 插件允许您在服务器和客户端之间创建多路通信会话。

。

添加依赖项

要使用 WebSockets，您需要在构建脚本中包含 ktor-client-websockets 构件：

Gradle (Kotlin)Gradle (Groovy)Maven

TIP

要了解更多关于 Ktor 客户端所需构件的信息，请参阅

添加客户端依赖项

了解如何向现有项目添加客户端依赖项。

。

安装 WebSockets

要安装 WebSockets 插件，请在 客户端配置块 内部将其传递给 install 函数：

配置

（可选）您可以通过在 install 块内传递 WebSockets.Config 支持的属性来配置插件。

<code>maxFrameSize</code>

设置可以接收或发送的最大 Frame 大小。

<code>contentConverter</code>

设置用于序列化/反序列化的转换器。

<code>pingIntervalMillis</code>

以 Long 格式指定 ping 之间的时间间隔。

<code>pingInterval</code>

以 Duration 格式指定 ping 之间的时间间隔。

pingInterval 和 pingIntervalMillis 属性不适用于 OkHttp 引擎。要为 OkHttp 设置 ping 间隔，您可以使用 引擎配置：

在以下示例中，WebSockets 插件配置了 20 秒（20_000 毫秒）的 ping 间隔，以自动发送 ping 帧并保持 WebSocket 连接处于活动状态：

使用 WebSocket 会话

客户端的 WebSocket 会话由 DefaultClientWebSocketSession 接口表示。该接口公开了允许您发送和接收 WebSocket 帧以及关闭会话的 API。

访问 WebSocket 会话

HttpClient 提供了两种访问 WebSocket 会话的主要方式：

• webSocket() 函数接受 DefaultClientWebSocketSession 作为块参数。
• webSocketSession() 函数返回 DefaultClientWebSocketSession 实例，并允许您在 runBlocking 或 launch 作用域之外访问会话。

处理 WebSocket 会话

在函数块内，您可以为指定的路径定义处理程序。块内提供以下函数和属性：

<code>send()</code>

使用 send() 函数向服务器发送文本内容。

<code>outgoing</code>

使用 outgoing 属性访问用于发送 WebSocket 帧的通道。帧由 Frame 类表示。

<code>incoming</code>

使用 incoming 属性访问用于接收 WebSocket 帧的通道。帧由 Frame 类表示。

<code>close()</code>

使用 close() 函数发送带有指定原因的关闭帧。

帧类型

您可以检查 WebSocket 帧的类型并进行相应处理。一些常见的帧类型包括：

• Frame.Text 表示文本帧。使用 Frame.Text.readText() 读取其内容。
• Frame.Binary 表示二进制帧。使用 Frame.Binary.readBytes() 读取其内容。
• Frame.Close 表示关闭帧。使用 Frame.Close.readReason() 获取会话关闭的原因。

示例

下面的示例创建了 echo WebSocket 端点，并展示了如何向服务器发送消息以及从服务器接收消息。

有关完整示例，请参阅 client-websockets。