Ktor 客户端中的 WebSockets 序列化

代码示例: client-websockets-serialization

与 ContentNegotiation 插件类似，WebSockets 允许你将文本帧序列化/反序列化为特定格式。Ktor 客户端开箱即用支持以下格式：JSON、XML、CBOR 和 ProtoBuf。

添加依赖项

在使用 kotlinx.serialization 转换器之前，你需要按照 Setup 章节中的说明添加 Kotlin 序列化插件。

JSON

要序列化/反序列化 JSON 数据，你可以选择以下库之一：kotlinx.serialization、Gson 或 Jackson。

kotlinx.serializationGsonJackson

在构建脚本中添加 ktor-serialization-kotlinx-json 构件：

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 序列化器，请创建一个 KotlinxWebsocketSerializationConverter 实例并使用 Json 形参，然后将此实例赋值给 contentConverter 属性：

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 序列化器，请创建一个 KotlinxWebsocketSerializationConverter 实例并使用 XML 形参，然后将此实例赋值给 contentConverter 属性：

import nl.adaptivity.xmlutil.serialization.*

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

CBOR 序列化器

要在 WebSockets 配置中注册 CBOR 序列化器，请创建一个 KotlinxWebsocketSerializationConverter 实例并使用 Cbor 形参，然后将此实例赋值给 contentConverter 属性：

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

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

ProtoBuf 序列化器

要在 WebSockets 配置中注册 ProtoBuf 序列化器，请创建一个 KotlinxWebsocketSerializationConverter 实例并使用 ProtoBuf 形参，然后将此实例赋值给 contentConverter 属性：

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

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

接收和发送数据

创建数据类

要将文本帧序列化到对象或从对象反序列化，你需要创建一个数据类，例如：

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

如果你使用 kotlinx.serialization，请确保此数据类带有 @Serializable 注解：

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

要了解更多关于 kotlinx.serialization 的信息，请参见 Kotlin 序列化指南。

发送数据

要在一个文本帧中以 指定格式 发送一个 类实例，请使用 sendSerialized 函数：

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

接收数据

要接收并转换文本帧的内容，请调用 receiveDeserialized 函数，该函数接受一个数据类作为形参：

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 通道接收反序列化的帧，请使用 WebsocketContentConverter.deserialize 函数。WebsocketContentConverter 可通过 DefaultClientWebSocketSession.converter 属性获取。

你可以在这里找到完整的示例：client-websockets-serialization。