Skip to content
Client Plugin

Ktor Client의 콘텐츠 협상 및 직렬화

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

코드 예제: client-json-kotlinx

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

  • Accept 및 Content-Type 헤더를 사용하여 클라이언트와 서버 간의 미디어 타입을 협상합니다.
  • 지원되는 형식으로 요청 본문을 직렬화하고 응답 본문을 역직렬화합니다. Ktor는 JSON, XML, CBOR, ProtoBuf를 기본적으로 지원합니다.

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

의존성 추가 ​

콘텐츠 협상 ​

ContentNegotiation을 사용하려면 빌드 스크립트에 ktor-client-content-negotiation 아티팩트를 추가하세요:

kotlin
implementation(ktorLibs.client.contentNegotiation)
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
groovy
implementation ktorLibs.client.contentNegotiation
위 코드 스니펫은 Ktor 의존성을 지정하기 위해 Ktor 버전 카탈로그를 사용합니다.
xml
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-content-negotiation-jvm</artifactId>
    <version>${ktor_version}</version>
</dependency>

특정 형식의 직렬 변환기(Serializer)는 추가 아티팩트가 필요합니다.

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

Ktor 클라이언트에 필요한 아티팩트에 대해 자세히 알아보려면 클라이언트 의존성 추가기존 프로젝트에 클라이언트 의존성을 추가하는 방법을 알아봅니다.를 참고하세요.

직렬화 ​

kotlinx.serialization 변환기를 사용하기 전에 Setup 섹션의 설명에 따라 Kotlin 직렬화 플러그인을 추가하세요.

JSON ​

JSON 데이터를 직렬화 및 역직렬화하려면 프로젝트에 직렬화 라이브러리를 추가하세요. Ktor는 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>

ContentNegotiation 설치 ​

ContentNegotiation 플러그인을 설치하려면 클라이언트 구성 블록의 install 함수에 전달하세요:

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

설치 후 필요한 JSON 직렬 변환기를 구성할 수 있습니다.

직렬 변환기 구성 ​

JSON 직렬 변환기 ​

애플리케이션에 JSON 직렬 변환기를 등록하려면 json() 함수를 호출합니다:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*

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

JSON 직렬화를 커스터마이즈하려면 json() 생성자에 Json 구성을 전달합니다:

kotlin
val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json(Json {
            prettyPrint = true
            isLenient = true
        })
    }
}

사용 가능한 구성 옵션은 JsonBuilder를 참고하세요.

전체 예제는 client-json-kotlinx를 참고하세요.

애플리케이션에 Gson 직렬 변환기를 등록하려면 gson() 함수를 호출합니다:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.gson.*

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

Gson 직렬화를 커스터마이즈하려면 gson() 함수에 구성 블록을 전달합니다. 사용 가능한 구성 옵션은 GsonBuilder를 참고하세요.

애플리케이션에 Jackson 직렬 변환기를 등록하려면 jackson() 함수를 호출합니다:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.jackson.*

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

Jackson 직렬화를 커스터마이즈하려면 ObjectMapper에서 제공하는 설정을 사용합니다:

kotlin
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() 함수를 호출합니다:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.xml.*

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

XML 직렬화를 커스터마이즈하려면 xml() 함수에 필요한 옵션을 전달합니다:

kotlin
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() 함수를 호출합니다:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.cbor.*

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

CBOR 직렬화를 커스터마이즈하려면 cbor() 생성자에 Cbor 구성을 전달합니다:

kotlin
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
        })
    }
}

사용 가능한 구성 옵션은 CborBuilder를 참고하세요.

ProtoBuf 직렬 변환기 ​

애플리케이션에 ProtoBuf 직렬 변환기를 등록하려면 protobuf() 함수를 호출합니다:

kotlin
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*

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

ProtoBuf 직렬화를 커스터마이즈하려면 protobuf() 함수에 ProtoBuf 구성을 전달합니다:

kotlin
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
        })
    }
}

사용 가능한 옵션은 ProtoBufBuilder를 참고하세요.

Accept 헤더 구성 ​

기본적으로 ContentNegotiation 플러그인은 나가는 요청의 Accept 헤더에 등록된 콘텐츠 타입을 추가합니다.

Accept 헤더를 명시적으로 설정하고 플러그인이 등록된 콘텐츠 타입을 추가하지 않도록 하려면 acceptHeaderMergeStrategy 속성을 ContentTypeMergeStrategy.SkipIfPresent로 설정하세요:

kotlin
val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        register(ContentType.Application.Json, noOpJsonConverter)
        acceptHeaderMergeStrategy = ContentTypeMergeStrategy.SkipIfPresent
    }
}

SkipIfPresent를 사용하면 플러그인이 기존 Accept 헤더를 유지합니다. 요청에 Accept 헤더가 없는 경우 플러그인은 평소처럼 등록된 콘텐츠 타입을 추가합니다.

데이터 전송 및 수신 ​

데이터 클래스 생성 ​

다음 예제에서는 클라이언트가 주고받는 데이터를 나타내기 위해 Customer 데이터 클래스를 사용합니다:

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 라이브러리는 다음 타입의 직렬화/역직렬화를 지원합니다:

데이터 전송 ​

요청 본문으로 클래스 인스턴스를 전송하려면 setBody() 함수를 사용해 이 인스턴스를 할당하고 contentType() 함수를 사용해 콘텐츠 타입을 설정합니다.

다음 예제는 Customer 객체를 JSON으로 전송합니다:

kotlin
val response: HttpResponse = client.post("http://localhost:8080/customer") {
    contentType(ContentType.Application.Json)
    setBody(Customer(3, "Jet", "Brains"))
}

ContentNegotiation 플러그인은 구성된 직렬 변환기를 사용하여 요청 본문을 지정된 형식으로 변환합니다.

등록된 다른 형식으로 데이터를 보내려면 ContentType.Application.Xml 또는 ContentType.Application.Cbor와 같이 해당 콘텐츠 타입을 지정하세요.

데이터 수신 ​

서버가 지원되는 콘텐츠 타입의 응답을 반환하면, ContentNegotiation 플러그인은 응답 본문을 기대하는 타입으로 역직렬화할 수 있습니다.

예를 들어 JSON 응답을 Customer 객체로 역직렬화하려면 body() 함수를 호출합니다:

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

전체 예제는 client-json-kotlinx를 참고하세요.