Ktor Server 中的 WebSockets 序列化
與 ContentNegotiation 外掛程式類似,WebSockets 允許你以特定格式序列化/反序列化文字訊框 (text frame)。Ktor 開箱即用支援以下格式:JSON、XML、CBOR 和 ProtoBuf。
新增相依性
在使用 kotlinx.serialization 轉換器之前,你需要按照 Setup 一節中的說明新增 Kotlin serialization 外掛程式。
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 函式。WebsocketContentConverter 可透過 WebSocketServerSession.converter 屬性取得。
傳送資料
若要使用指定的格式在文字訊框中傳遞資料物件,你可以使用 sendSerialized 函式:
webSocket("/customer/1") {
sendSerialized(Customer(1, "Jane", "Smith"))
}你可以在這裡找到完整範例:server-websockets-serialization。
