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 아티팩트를 추가하세요:
implementation(ktorLibs.client.contentNegotiation)implementation ktorLibs.client.contentNegotiation<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가 기본 직렬 변환기를 자동으로 선택합니다. 필요한 경우 직렬 변환기를 명시적으로 지정하고 구성할 수 있습니다.
직렬화
kotlinx.serialization 변환기를 사용하기 전에 Setup 섹션의 설명에 따라 Kotlin 직렬화 플러그인을 추가하세요.
JSON
JSON 데이터를 직렬화 및 역직렬화하려면 프로젝트에 직렬화 라이브러리를 추가하세요. Ktor는 kotlinx.serialization, Gson 또는 Jackson을 지원합니다.
빌드 스크립트에 ktor-serialization-kotlinx-json 아티팩트를 추가하세요:
implementation(ktorLibs.serialization.kotlinx.json)implementation ktorLibs.serialization.kotlinx.json<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-json-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>빌드 스크립트에 ktor-serialization-gson 아티팩트를 추가하세요:
implementation(ktorLibs.serialization.gson)implementation ktorLibs.serialization.gson<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-gson-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>빌드 스크립트에 ktor-serialization-jackson 아티팩트를 추가하세요:
implementation(ktorLibs.serialization.jackson)implementation ktorLibs.serialization.jackson<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-jackson-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>XML
XML을 직렬화 및 역직렬화하려면 빌드 스크립트에 ktor-serialization-kotlinx-xml 아티팩트를 추가하세요:
implementation(ktorLibs.serialization.kotlinx.xml)implementation ktorLibs.serialization.kotlinx.xml<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-xml-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>CBOR
CBOR을 직렬화 및 역직렬화하려면 빌드 스크립트에 ktor-serialization-kotlinx-cbor 아티팩트를 추가하세요:
implementation(ktorLibs.serialization.kotlinx.cbor)implementation ktorLibs.serialization.kotlinx.cbor<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-cbor-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>ProtoBuf
ProtoBuf를 직렬화 및 역직렬화하려면 빌드 스크립트에 ktor-serialization-kotlinx-protobuf 아티팩트를 추가하세요:
implementation(ktorLibs.serialization.kotlinx.protobuf)implementation ktorLibs.serialization.kotlinx.protobuf<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-serialization-kotlinx-protobuf-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>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 직렬화를 커스터마이즈하려면 json() 생성자에 Json 구성을 전달합니다:
val client = HttpClient(CIO) {
install(ContentNegotiation) {
json(Json {
prettyPrint = true
isLenient = true
})
}
}사용 가능한 구성 옵션은 JsonBuilder를 참고하세요.
전체 예제는 client-json-kotlinx를 참고하세요.
애플리케이션에 Gson 직렬 변환기를 등록하려면 gson() 함수를 호출합니다:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.gson.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
gson()
}
}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 직렬화를 커스터마이즈하려면 cbor() 생성자에 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
})
}
}사용 가능한 구성 옵션은 CborBuilder를 참고하세요.
ProtoBuf 직렬 변환기
애플리케이션에 ProtoBuf 직렬 변환기를 등록하려면 protobuf() 함수를 호출합니다:
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.protobuf.*
val client = HttpClient(CIO) {
install(ContentNegotiation) {
protobuf()
}
}ProtoBuf 직렬화를 커스터마이즈하려면 protobuf() 함수에 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
})
}
}사용 가능한 옵션은 ProtoBufBuilder를 참고하세요.
Accept 헤더 구성
기본적으로 ContentNegotiation 플러그인은 나가는 요청의 Accept 헤더에 등록된 콘텐츠 타입을 추가합니다.
Accept 헤더를 명시적으로 설정하고 플러그인이 등록된 콘텐츠 타입을 추가하지 않도록 하려면 acceptHeaderMergeStrategy 속성을 ContentTypeMergeStrategy.SkipIfPresent로 설정하세요:
val client = HttpClient(CIO) {
install(ContentNegotiation) {
register(ContentType.Application.Json, noOpJsonConverter)
acceptHeaderMergeStrategy = ContentTypeMergeStrategy.SkipIfPresent
}
}SkipIfPresent를 사용하면 플러그인이 기존 Accept 헤더를 유지합니다. 요청에 Accept 헤더가 없는 경우 플러그인은 평소처럼 등록된 콘텐츠 타입을 추가합니다.
데이터 전송 및 수신
데이터 클래스 생성
다음 예제에서는 클라이언트가 주고받는 데이터를 나타내기 위해 Customer 데이터 클래스를 사용합니다:
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 라이브러리는 다음 타입의 직렬화/역직렬화를 지원합니다:
- 내장 클래스(Builtin classes)
- Sequence 역직렬화
- Flow 직렬화
데이터 전송
요청 본문으로 클래스 인스턴스를 전송하려면 setBody() 함수를 사용해 이 인스턴스를 할당하고 contentType() 함수를 사용해 콘텐츠 타입을 설정합니다.
다음 예제는 Customer 객체를 JSON으로 전송합니다:
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() 함수를 호출합니다:
val customer: Customer = client.get("http://localhost:8080/customer/3").body()전체 예제는 client-json-kotlinx를 참고하세요.
