Ktor 서버의 웹소켓 직렬화

코드 예시: server-websockets-serialization

[ContentNegotiation](server-serialization.md) 플러그인과 유사하게, 웹소켓은 특정 형식으로 텍스트 프레임을 직렬화/역직렬화할 수 있게 해줍니다. Ktor는 JSON, XML, CBOR, ProtoBuf와 같은 형식을 기본적으로 지원합니다.

의존성 추가

kotlinx.serialization 컨버터를 사용하기 전에, [Setup](https://github.com/Kotlin/kotlinx.serialization#setup) 섹션에 설명된 대로 Kotlin 직렬화 플러그인을 추가해야 합니다.

JSON

JSON 데이터를 직렬화/역직렬화하려면 다음 라이브러리 중 하나를 선택할 수 있습니다: kotlinx.serialization, Gson, 또는 Jackson.

kotlinx.serializationGsonJackson

빌드 스크립트에 ktor-serialization-kotlinx-json 아티팩트를 추가하세요:

Gradle (Kotlin)Gradle (Groovy)Maven

빌드 스크립트에 ktor-serialization-gson 아티팩트를 추가하세요:

Gradle (Kotlin)Gradle (Groovy)Maven

빌드 스크립트에 ktor-serialization-jackson 아티팩트를 추가하세요:

Gradle (Kotlin)Gradle (Groovy)Maven

XML

XML을 직렬화/역직렬화하려면 빌드 스크립트에 ktor-serialization-kotlinx-xml을 추가하세요:

Gradle (Kotlin)Gradle (Groovy)Maven

Note that XML serialization is not supported on jsNode target.

CBOR

CBOR을 직렬화/역직렬화하려면 빌드 스크립트에 ktor-serialization-kotlinx-cbor을 추가하세요:

Gradle (Kotlin)Gradle (Groovy)Maven

ProtoBuf

ProtoBuf를 직렬화/역직렬화하려면 빌드 스크립트에 ktor-serialization-kotlinx-protobuf을 추가하세요:

Gradle (Kotlin)Gradle (Groovy)Maven

직렬 변환기 구성

JSON 직렬 변환기

kotlinx.serializationGsonJackson

웹소켓 [구성](server-websockets.md#configure)에서 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 직렬 변환기

웹소켓 [구성](server-websockets.md#configure)에서 XML 직렬 변환기를 등록하려면, XML 매개변수를 사용하여 KotlinxWebsocketSerializationConverter 인스턴스를 생성하고 이 인스턴스를 contentConverter 속성에 할당하세요:

import nl.adaptivity.xmlutil.serialization.*

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

CBOR 직렬 변환기

웹소켓 [구성](server-websockets.md#configure)에서 CBOR 직렬 변환기를 등록하려면, Cbor 매개변수를 사용하여 KotlinxWebsocketSerializationConverter 인스턴스를 생성하고 이 인스턴스를 contentConverter 속성에 할당하세요:

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

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

ProtoBuf 직렬 변환기

웹소켓 [구성](server-websockets.md#configure)에서 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](server-websockets.md#api-overview) 채널에서 역직렬화된 프레임을 수신하려면 [WebsocketContentConverter.deserialize](https://api.ktor.io/ktor-shared/ktor-serialization/io.ktor.serialization/-websocket-content-converter/deserialize.html) 함수를 사용하세요. WebsocketContentConverter는 WebSocketServerSession.converter 속성을 통해 사용할 수 있습니다.

데이터 전송

[지정된 형식](#configure_serializer)을 사용하여 텍스트 프레임에 데이터 객체를 전달하려면 sendSerialized 함수를 사용할 수 있습니다:

webSocket("/customer/1") {
    sendSerialized(Customer(1, "Jane", "Smith"))
}

전체 예제는 다음에서 찾을 수 있습니다: server-websockets-serialization.