Ktor Client 中的 WebSockets 序列化

程式碼範例: client-websockets-serialization

與 ContentNegotiation 插件（plugin）類似，WebSockets 允許您將文字幀（text frames）序列化/反序列化為特定格式。Ktor 客戶端（client）開箱即用地支援以下格式：JSON、XML、CBOR 和 ProtoBuf。

添加依賴項

在使用 kotlinx.serialization 轉換器（converter）之前，您需要如 設置 部分所述添加 Kotlin 序列化插件。

JSON

要序列化/反序列化 JSON 數據，您可以選擇以下函式庫（library）之一：kotlinx.serialization、Gson 或 Jackson。

kotlinx.serializationGsonJackson

在建構腳本（build script）中添加 ktor-serialization-kotlinx-json 構件（artifact）：

Gradle (Kotlin)Gradle (Groovy)Maven

在建構腳本中添加 ktor-serialization-gson 構件：

Gradle (Kotlin)Gradle (Groovy)Maven

在建構腳本中添加 ktor-serialization-jackson 構件：

Gradle (Kotlin)Gradle (Groovy)Maven

XML

要序列化/反序列化 XML，請在建構腳本中添加 ktor-serialization-kotlinx-xml：

Gradle (Kotlin)Gradle (Groovy)Maven

注意，XML 序列化 在 jsNode 目標上不受支援。

CBOR

要序列化/反序列化 CBOR，請在建構腳本中添加 ktor-serialization-kotlinx-cbor：

Gradle (Kotlin)Gradle (Groovy)Maven

ProtoBuf

要序列化/反序列化 ProtoBuf，請在建構腳本中添加 ktor-serialization-kotlinx-protobuf：

Gradle (Kotlin)Gradle (Groovy)Maven

配置序列化器

JSON 序列化器

kotlinx.serializationGsonJackson

要在 WebSockets 配置 中註冊 JSON 序列化器，請使用 Json 參數建立一個 KotlinxWebsocketSerializationConverter 實例（instance），並將此實例分配給 contentConverter 屬性（property）：

import io.ktor.serialization.kotlinx.*
import kotlinx.serialization.json.*

val client = HttpClient(CIO) {
    install(WebSockets) {
        contentConverter = KotlinxWebsocketSerializationConverter(Json)
    }
}

要註冊 Gson 序列化器，請將 GsonWebsocketContentConverter 分配給 contentConverter 屬性：

import io.ktor.serialization.gson.*

install(WebSockets) {
    contentConverter = GsonWebsocketContentConverter()
}

要註冊 Jackson 序列化器，請將 JacksonWebsocketContentConverter 分配給 contentConverter 屬性：

import io.ktor.serialization.jackson.*

install(WebSockets) {
    contentConverter = JacksonWebsocketContentConverter()
}

XML 序列化器

要在 WebSockets 配置 中註冊 XML 序列化器，請使用 XML 參數建立一個 KotlinxWebsocketSerializationConverter 實例，並將此實例分配給 contentConverter 屬性：

import nl.adaptivity.xmlutil.serialization.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(XML)
}

CBOR 序列化器

要在 WebSockets 配置 中註冊 CBOR 序列化器，請使用 Cbor 參數建立一個 KotlinxWebsocketSerializationConverter 實例，並將此實例分配給 contentConverter 屬性：

import io.ktor.serialization.kotlinx.cbor.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(Cbor)
}

ProtoBuf 序列化器

要在 WebSockets 配置 中註冊 ProtoBuf 序列化器，請使用 ProtoBuf 參數建立一個 KotlinxWebsocketSerializationConverter 實例，並將此實例分配給 contentConverter 屬性：

import io.ktor.serialization.kotlinx.protobuf.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(ProtoBuf)
}

接收和發送數據

建立資料類別

要將文字幀序列化為物件（object）或從物件反序列化，您需要建立一個資料類別（data class），例如：

data class Customer(val id: Int, val firstName: String, val lastName: String)

如果您使用 kotlinx.serialization，請確保此類別具有 @Serializable 註解（annotation）：

@Serializable
data class Customer(val id: Int, val firstName: String, val lastName: String)

要了解有關 kotlinx.serialization 的更多資訊，請參閱 Kotlin Serialization Guide。

發送數據

要在文字幀中以指定格式 發送類別實例，請使用 sendSerialized 函式（function）：

client.webSocket(method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/customer") {
    sendSerialized(Customer(1, "Jane", "Smith"))
}

接收數據

要接收並轉換文字幀的內容，請呼叫 receiveDeserialized 函式，它接受一個資料類別作為參數（parameter）：

client.webSocket(method = HttpMethod.Get, host = "127.0.0.1", port = 8080, path = "/customer/1") {
    val customer = receiveDeserialized<Customer>()
    println("A customer with id ${customer.id} is received by the client.")
}

要從 傳入通道（incoming channel） 接收反序列化的幀，請使用 WebsocketContentConverter.deserialize 函式。WebsocketContentConverter 可透過 DefaultClientWebSocketSession.converter 屬性取得。

您可以在此處找到完整的範例：client-websockets-serialization。