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。