Skip to content

Ktor Client의 WebSockets 직렬화 ​

ContentNegotiation 플러그인과 마찬가지로, WebSockets를 사용하면 텍스트 프레임을 특정 형식으로 직렬화/역직렬화할 수 있습니다. Ktor 클라이언트는 JSON, XML, CBOR, ProtoBuf 형식을 기본적으로 지원합니다.

의존성 추가 ​

kotlinx.serialization 컨버터를 사용하기 전에, Setup 섹션의 설명에 따라 Kotlin serialization 플러그인을 추가해야 합니다.

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 Serialization Guide를 참조하세요.

데이터 전송 ​

지정된 형식의 텍스트 프레임 내에서 클래스 인스턴스를 전송하려면 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.