Ktor 클라이언트의 콘텐츠 협상 및 직렬화
필수 의존성: io.ktor:ktor-client-content-negotiation
코드 예제: client-json-kotlinx
ContentNegotiation 플러그인은 두 가지 주요 목적을 수행합니다:
- 클라이언트와 서버 간의 미디어 타입(Media types)을 협상합니다. 이를 위해
Accept및Content-Type헤더를 사용합니다. - 요청(Requests)을 보내고 응답(Responses)을 받을 때 콘텐츠를 특정 형식으로 직렬화(Serializing)/역직렬화(Deserializing)합니다. Ktor는 JSON, XML, CBOR, ProtoBuf 형식을 기본적으로 지원합니다.
서버 측에서 Ktor는 콘텐츠 직렬화/역직렬화를 위한 ContentNegotiation 플러그인을 제공합니다.
의존성 추가
ContentNegotiation
ContentNegotiation을 사용하려면 빌드 스크립트에 ktor-client-content-negotiation 아티팩트를 포함해야 합니다:
TIP
Ktor 클라이언트에 필요한 아티팩트에 대한 자세한 내용은특정 형식에 대한 직렬화기(Serializer)에는 추가 아티팩트가 필요합니다. 예를 들어, JSON을 위한 kotlinx.serialization은 ktor-serialization-kotlinx-json 의존성이 필요합니다. 포함된 아티팩트에 따라 Ktor는 자동으로 기본 직렬화기를 선택합니다. 필요한 경우 직렬화기를 명시적으로 지정하고 구성할 수 있습니다.
직렬화 (Serialization)
kotlinx.serialization 컨버터를 사용하기 전에 설정(Setup) 섹션에 설명된 대로 Kotlin 직렬화 플러그인을 추가해야 합니다.
JSON
JSON 데이터를 직렬화/역직렬화하기 위해 kotlinx.serialization, Gson, Jackson 라이브러리 중 하나를 선택할 수 있습니다.
빌드 스크립트에 ktor-serialization-kotlinx-json 아티팩트를 추가합니다:
빌드 스크립트에 ktor-serialization-gson 아티팩트를 추가합니다:
빌드 스크립트에 ktor-serialization-jackson 아티팩트를 추가합니다:
XML
XML을 직렬화/역직렬화하려면 빌드 스크립트에 ktor-serialization-kotlinx-xml을 추가합니다:
XML 직렬화는
jsNode타겟에서 지원되지 않습니다.
CBOR
CBOR을 직렬화/역직렬화하려면 빌드 스크립트에 ktor-serialization-kotlinx-cbor을 추가합니다:
ProtoBuf
ProtoBuf를 직렬화/역직렬화하려면 빌드 스크립트에 ktor-serialization-kotlinx-protobuf를 추가합니다:
ContentNegotiation 설치
ContentNegotiation을 설치하려면 클라이언트 구성 블록 내부의 install 함수에 전달합니다:
val client = HttpClient(CIO) {
install(ContentNegotiation)
}이제 필요한 JSON 직렬화기를 구성할 수 있습니다.
직렬화기 구성
JSON 직렬화기
애플리케이션에 JSON 직렬화기를 등록하려면 json 메서드를 호출합니다:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
json()
}
}json 생성자에서 JsonBuilder API에 접근할 수 있습니다. 예:
val client = HttpClient(CIO) {
install(ContentNegotiation) {
json(Json {
prettyPrint = true
isLenient = true
})
}
}전체 예제는 여기에서 확인할 수 있습니다: client-json-kotlinx.
애플리케이션에 Gson 직렬화기를 등록하려면 gson 메서드를 호출합니다:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.gson.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
gson()
}
}gson 메서드를 사용하면 GsonBuilder에서 제공하는 직렬화 설정을 조정할 수도 있습니다.
애플리케이션에 Jackson 직렬화기를 등록하려면 jackson 메서드를 호출합니다:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
jackson()
}
}jackson 메서드를 사용하면 ObjectMapper에서 제공하는 직렬화 설정을 조정할 수도 있습니다. 예:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*
import com.fasterxml.jackson.databind.*
import java.text.DateFormat
val client = HttpClient(CIO) {
install(ContentNegotiation) {
jackson {
enable(SerializationFeature.INDENT_OUTPUT)
dateFormat = DateFormat.getDateInstance()
}
}
}XML 직렬화기
애플리케이션에 XML 직렬화기를 등록하려면 xml 메서드를 호출합니다:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
xml()
}
}xml 메서드를 사용하면 XML 직렬화 설정에 접근할 수도 있습니다. 예:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*
import nl.adaptivity.xmlutil.*
import nl.adaptivity.xmlutil.serialization.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
xml(format = XML {
xmlDeclMode = XmlDeclMode.Charset
})
}
}CBOR 직렬화기
애플리케이션에 CBOR 직렬화기를 등록하려면 cbor 메서드를 호출합니다:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
cbor()
}
}cbor 메서드를 사용하면 CborBuilder에서 제공하는 CBOR 직렬화 설정에 접근할 수도 있습니다. 예:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*
import kotlinx.serialization.cbor.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
cbor(Cbor {
ignoreUnknownKeys = true
})
}
}ProtoBuf 직렬화기
애플리케이션에 ProtoBuf 직렬화기를 등록하려면 protobuf 메서드를 호출합니다:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
protobuf()
}
}protobuf 메서드를 사용하면 ProtoBufBuilder에서 제공하는 ProtoBuf 직렬화 설정에 접근할 수도 있습니다. 예:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*
import kotlinx.serialization.protobuf.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
protobuf(ProtoBuf {
encodeDefaults = true
})
}
}데이터 받기 및 보내기
데이터 클래스 생성
데이터를 주고받으려면 데이터 클래스가 필요합니다. 예:
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)다음 타입의 직렬화/역직렬화는 kotlinx.serialization 라이브러리에 의해 지원됩니다:
데이터 보내기
요청(Request) 바디에 클래스 인스턴스를 JSON으로 보내려면, setBody 함수를 사용하여 이 인스턴스를 할당하고 contentType을 호출하여 콘텐츠 타입을 application/json으로 설정합니다:
val response: HttpResponse = client.post("http://localhost:8080/customer") {
contentType(ContentType.Application.Json)
setBody(Customer(3, "Jet", "Brains"))
}데이터를 XML 또는 CBOR로 보내려면 contentType을 각각 ContentType.Application.Xml 또는 ContentType.Application.Cbor로 설정합니다.
데이터 받기
서버가 application/json, application/xml 또는 application/cbor 콘텐츠를 포함한 응답(Response)을 보낼 때, 응답 페이로드를 받는 데 사용되는 함수(아래 예제의 body)의 파라미터로 데이터 클래스를 지정하여 역직렬화할 수 있습니다:
val customer: Customer = client.get("http://localhost:8080/customer/3").body()전체 예제는 여기에서 확인할 수 있습니다: client-json-kotlinx.