Ktor Server 中的 WebSockets 序列化
与 ContentNegotiation 插件类似,WebSockets 允许你以特定格式序列化/反序列化文本帧。Ktor 开箱即用支持以下格式:JSON、XML、CBOR 和 ProtoBuf。
添加依赖项
在使用 kotlinx.serialization 转换器之前,你需要按照 Setup 部分中所述添加 Kotlin 序列化插件。
JSON
要序列化/反序列化 JSON 数据,你可以选择以下库之一:kotlinx.serialization、Gson 或 Jackson。
在构建脚本中添加 ktor-serialization-kotlinx-json 工件:
implementation(ktorLibs.serialization.kotlinx.json)implementation ktorLibs.serialization.kotlinx.json<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-json-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>在构建脚本中添加 ktor-serialization-gson 工件:
implementation(ktorLibs.serialization.gson)implementation ktorLibs.serialization.gson<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-gson-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>在构建脚本中添加 ktor-serialization-jackson 工件:
implementation(ktorLibs.serialization.jackson)implementation ktorLibs.serialization.jackson<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-jackson-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>XML
要序列化/反序列化 XML,请在构建脚本中添加 ktor-serialization-kotlinx-xml:
implementation(ktorLibs.serialization.kotlinx.xml)implementation ktorLibs.serialization.kotlinx.xml<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-xml-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>CBOR
要序列化/反序列化 CBOR,请在构建脚本中添加 ktor-serialization-kotlinx-cbor:
implementation(ktorLibs.serialization.kotlinx.cbor)implementation ktorLibs.serialization.kotlinx.cbor<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-cbor-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>ProtoBuf
要序列化/反序列化 ProtoBuf,请在构建脚本中添加 ktor-serialization-kotlinx-protobuf:
implementation(ktorLibs.serialization.kotlinx.protobuf)implementation ktorLibs.serialization.kotlinx.protobuf<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>配置序列化器
JSON 序列化器
要在 WebSockets 配置中注册 JSON 序列化器,请使用 Json 形参创建 KotlinxWebsocketSerializationConverter 实例,并将该实例赋值给 contentConverter 属性:
import io.ktor.serialization.kotlinx.*
import kotlinx.serialization.json.*
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 kotlinx.serialization.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)接收数据
要接收并转换文本帧的内容,调用接受数据类作为形参的 receiveDeserialized 函数:
webSocket("/customer") {
val customer = receiveDeserialized<Customer>()
println("A customer with id ${customer.id} is received by the server.")
}要从 incoming 通道接收反序列化的帧,请使用 WebsocketContentConverter.deserialize 函数。可通过 WebSocketServerSession.converter 属性访问 WebsocketContentConverter。
发送数据
要使用指定的格式在文本帧中传递数据对象,可以使用 sendSerialized 函数:
webSocket("/customer/1") {
sendSerialized(Customer(1, "Jane", "Smith"))
}可以在此处找到完整示例:server-websockets-serialization。
