Client Plugin

Ktor Client에서 콘텐츠 협상 및 직렬화

필수 의존성: io.ktor:ktor-client-content-negotiation

코드 예시: client-json-kotlinx

ContentNegotiation 플러그인은 두 가지 주요 목적을 제공합니다:

• 클라이언트와 서버 간의 미디어 타입 협상. 이를 위해 Accept 및 Content-Type 헤더를 사용합니다.
• 요청을 보내고 응답을 받을 때 특정 형식으로 콘텐츠를 직렬화/역직렬화. Ktor는 기본적으로 JSON, XML, CBOR, ProtoBuf 형식을 지원합니다. XML 직렬 변환기는 JVM에서만 지원됩니다.

서버에서는 Ktor가 콘텐츠 직렬화/역직렬화를 위해 ContentNegotiation 플러그인을 제공합니다.

의존성 추가

ContentNegotiation

ContentNegotiation을(를) 사용하려면 빌드 스크립트에 ktor-client-content-negotiation 아티팩트를 포함해야 합니다:

Gradle (Kotlin)Gradle (Groovy)Maven

Ktor 클라이언트에 필요한 아티팩트에 대한 자세한 내용은

클라이언트 의존성 추가하기

기존 프로젝트에 클라이언트 의존성을 추가하는 방법을 알아보세요.

에서 확인할 수 있습니다.

특정 형식의 직렬 변환기는 추가 아티팩트를 필요로 합니다. 예를 들어, kotlinx.serialization은 JSON을 위해 ktor-serialization-kotlinx-json 의존성을 필요로 합니다. 포함된 아티팩트에 따라 Ktor는 자동으로 기본 직렬 변환기를 선택합니다. 필요한 경우, 직렬 변환기를 명시적으로 지정하고 구성할 수 있습니다.

직렬화

kotlinx.serialization 변환기를 사용하기 전에 설정 섹션에 설명된 대로 Kotlin serialization 플러그인을 추가해야 합니다.

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

XML 직렬화는 jsNode 타겟에서 지원되지 않습니다.

CBOR

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

Gradle (Kotlin)Gradle (Groovy)Maven

ProtoBuf

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

Gradle (Kotlin)Gradle (Groovy)Maven

ContentNegotiation 설치

ContentNegotiation을 설치하려면 클라이언트 구성 블록 내부의 install 함수에 전달합니다:

val client = HttpClient(CIO) {
    install(ContentNegotiation)
}

이제 필요한 JSON 직렬 변환기를 구성할 수 있습니다.

직렬 변환기 구성

JSON 직렬 변환기

kotlinx.serializationGsonJackson

애플리케이션에 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에서 제공하는 직렬화 설정을 조정할 수도 있습니다.

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.adaptivety.xmlutil.*
import nl.adaptivety.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 라이브러리에서 지원됩니다:

• 내장 클래스
• 시퀀스의 역직렬화
• 플로우의 직렬화

데이터 전송

요청 본문 내에서 클래스 인스턴스를 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 콘텐츠가 포함된 응답을 보낼 때, 응답 페이로드(body 함수)를 수신하는 데 사용되는 함수의 매개변수로 데이터 클래스를 지정하여 역직렬화할 수 있습니다:

val customer: Customer = client.get("http://localhost:8080/customer/3").body()

전체 예시는 client-json-kotlinx에서 찾을 수 있습니다.