WebSockets

Client Plugin

Ktor Client 中的 WebSockets

必要的相依性：io.ktor:ktor-client-websockets

程式碼範例： client-websockets

WebSocket 是一種協定，可透過單一 TCP 連線在用戶端的瀏覽器與伺服器之間提供全雙工 (full-duplex) 通訊工作階段。對於建立需要與伺服器進行即時資料傳輸的應用程式而言，它特別有用。 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。