Skip to content

Ktor Client 中的 WebSockets 序列化 ​

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

添加依赖项 ​

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

JSON ​

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

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

kotlin
implementation(ktorLibs.serialization.kotlinx.json)
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.kotlinx.json
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-json-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

在构建脚本中添加 ktor-serialization-gson 工件:

kotlin
implementation(ktorLibs.serialization.gson)
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.gson
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-gson-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

在构建脚本中添加 ktor-serialization-jackson 工件:

kotlin
implementation(ktorLibs.serialization.jackson)
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.jackson
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-jackson-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

XML ​

要序列化/反序列化 XML,请在构建脚本中添加 ktor-serialization-kotlinx-xml:

kotlin
implementation(ktorLibs.serialization.kotlinx.xml)
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.kotlinx.xml
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-xml-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

CBOR ​

要序列化/反序列化 CBOR,请在构建脚本中添加 ktor-serialization-kotlinx-cbor:

kotlin
implementation(ktorLibs.serialization.kotlinx.cbor)
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.kotlinx.cbor
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-cbor-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

ProtoBuf ​

要序列化/反序列化 ProtoBuf,请在构建脚本中添加 ktor-serialization-kotlinx-protobuf:

kotlin
implementation(ktorLibs.serialization.kotlinx.protobuf)
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
groovy
implementation ktorLibs.serialization.kotlinx.protobuf
上述代码段使用 Ktor 版本目录 来指定 Ktor 依赖项。
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

配置序列化器 ​

JSON 序列化器 ​

要在 WebSockets 配置中注册 JSON 序列化器,请创建一个带有 Json 形参的 KotlinxWebsocketSerializationConverter 实例,并将该实例赋值给 contentConverter 属性:

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

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

要注册 Gson 序列化器,请将 GsonWebsocketContentConverter 赋值给 contentConverter 属性:

kotlin
import io.ktor.serialization.gson.*

install(WebSockets) {
    contentConverter = GsonWebsocketContentConverter()
}

要注册 Jackson 序列化器,请将 JacksonWebsocketContentConverter 赋值给 contentConverter 属性:

kotlin
import io.ktor.serialization.jackson.*

install(WebSockets) {
    contentConverter = JacksonWebsocketContentConverter()
}

XML 序列化器 ​

要在 WebSockets 配置中注册 XML 序列化器,请创建一个带有 XML 形参的 KotlinxWebsocketSerializationConverter 实例,并将该实例赋值给 contentConverter 属性:

kotlin
import nl.adaptivity.xmlutil.serialization.*

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

CBOR 序列化器 ​

要在 WebSockets 配置中注册 CBOR 序列化器,请创建一个带有 Cbor 形参的 KotlinxWebsocketSerializationConverter 实例,并将该实例赋值给 contentConverter 属性:

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

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

ProtoBuf 序列化器 ​

要在 WebSockets 配置中注册 ProtoBuf 序列化器,请创建一个带有 ProtoBuf 形参的 KotlinxWebsocketSerializationConverter 实例,并将该实例赋值给 contentConverter 属性:

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

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

接收和发送数据 ​

创建数据类 ​

要在对象与文本帧之间进行序列化/反序列化,你需要创建一个数据类,例如:

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

如果你使用 kotlinx.serialization,请确保该类带有 @Serializable 注解:

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

要详细了解 kotlinx.serialization,请参阅 Kotlin 序列化指南。

发送数据 ​

要在文本帧中以指定格式发送类实例,请使用 sendSerialized 函数:

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

接收数据 ​

要接收并转换文本帧的内容,请调用接受数据类作为参数的 receiveDeserialized 函数:

kotlin
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。