Kotlin Academy · 강의

콘텐츠 협상과 kotlinx.serialization

JSON 직렬화를 구성하고 요청 본문을 자동으로 역직렬화해 보세요.

레슨 3/413개 단계

콘텐츠 협상과 kotlinx.serialization은(는) CoddyKit의 무료 Kotlin Academy 강의입니다. 이것은 4개 중 3번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 Kotlin Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. Kotlin Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

콘텐츠 협상이란 무엇입니까

콘텐츠 협상은 클라이언트와 서버가 응답 본문의 형식에 합의하는 HTTP 메커니즘입니다. 클라이언트가 Accept 헤더를 보내면 서버가 가장 잘 일치하는 형식을 선택합니다. Ktor의 ContentNegotiation 플러그인이 이 과정을 자동화합니다.

의존성 추가하기

ContentNegotiation 플러그인과 kotlinx.serialization JSON 변환기를 추가합니다:

dependencies {
    implementation("io.ktor:ktor-server-content-negotiation:2.3.12")
    implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.12")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
}

ContentNegotiation 설치하기

애플리케이션 모듈에 플러그인을 설치하고 JSON 변환기를 등록합니다:

import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*

fun Application.configureSerialization() {
    install(ContentNegotiation) {
        json()
    }
}

@Serializable 데이터 클래스

kotlinx.serialization의 @Serializable로 데이터 클래스에 애너테이션을 지정합니다. Kotlin 컴파일러 플러그인이 컴파일 시 직렬화기를 생성하므로 런타임에 리플렉션이 필요하지 않습니다:

import kotlinx.serialization.Serializable

@Serializable
data class User(val id: Long, val name: String, val email: String)

직렬화 가능한 객체로 응답하기

ContentNegotiation을 설치한 후에는 @Serializable 객체를 call.respond()에 전달합니다. Ktor가 객체를 자동으로 JSON으로 직렬화합니다:

get("/users/{id}") {
    val user = User(1L, "Alice", "alice@example.com")
    call.respond(user)  // serialized to JSON
}

직렬화 가능한 객체 받기

call.receive<T>()를 사용하여 요청 본문을 @Serializable 클래스로 역직렬화합니다. 본문의 형식이 잘못된 경우 Ktor가 ContentTransformationException을 발생시킵니다:

post("/users") {
    val newUser = call.receive<User>()
    call.respond(HttpStatusCode.Created, newUser)
}

JSON 구성 맞춤 설정하기

Json 인스턴스를 json()에 전달하여 직렬화를 맞춤 설정합니다. 알 수 없는 키 무시, 보기 좋게 출력, 관대한 모드 사용 등을 설정할 수 있습니다:

install(ContentNegotiation) {
    json(Json {
        prettyPrint = true
        isLenient = true
        ignoreUnknownKeys = true
    })
}

여러 콘텐츠 유형

서로 다른 Accept 유형을 지원하려면 여러 변환기를 등록합니다. Ktor는 클라이언트의 Accept 헤더와 일치하는 첫 번째 변환기를 선택합니다:

install(ContentNegotiation) {
    json()
    // xml() with ktor-serialization-kotlinx-xml if needed
}

목록과 맵 직렬화하기

컬렉션을 응답 객체로 감싸거나 call.respond(list)를 직접 사용합니다. 요소 유형이 @Serializable이면 kotlinx.serialization이 List<T>, Map<K,V> 및 중첩 제네릭을 처리합니다:

get("/users") {
    val users = listOf(
        User(1, "Alice", "a@example.com"),
        User(2, "Bob", "b@example.com")
    )
    call.respond(users)
}

사용자 지정 직렬화기

직접 소유하지 않은 유형(예: java.time.Instant)의 경우 KSerializer<T>를 구현하고 @Serializable(with = MySerializer::class) 또는 컨텍스트 직렬화 모듈을 통해 등록합니다:

val module = SerializersModule {
    contextual(Instant::class, InstantSerializer)
}
install(ContentNegotiation) {
    json(Json { serializersModule = module })
}

역직렬화 실패 오류 처리

StatusPages 플러그인을 설치하여 call.receive()가 실패할 때 깔끔한 오류 응답을 반환하도록 하십시오:

install(StatusPages) {
    exception<ContentTransformationException> { call, _ ->
        call.respond(HttpStatusCode.BadRequest, "Invalid request body")
    }
}

빠른 확인

kotlinx.serialization로 직렬화할 수 있도록 하려면 Kotlin 데이터 클래스에 어떤 애너테이션이 필요한가요?

인터랙티브 레슨에서 답해보세요

복습: 콘텐츠 협상과 kotlinx.serialization

핵심 내용:

자동 JSON 직렬화 및 역직렬화를 위해 ContentNegotiation과 json()을 설치하십시오
데이터 클래스에 @Serializable을 지정하십시오
직렬화에는 call.respond(obj)를, 역직렬화에는 call.receive()를 사용하십시오
Json { ... } 인스턴스를 json()에 전달하여 사용자 지정하십시오
역직렬화 오류를 적절하게 처리하려면 StatusPages를 사용하십시오

무료로 시작

AI 튜터와 함께 Kotlin을(를) 배우세요 — 무료

브라우저에서 실제 코드를 작성하고 실행하며, 24/7 AI 튜터로부터 즉각적인 도움을 받고, 웹이나 앱에서 중단한 부분부터 계속 학습하세요.

코스: 51
레슨: 203

무료로 학습 시작 전체 코스 보기

자주 묻는 질문

“콘텐츠 협상과 kotlinx.serialization” 강의는 무료인가요?

네 — “콘텐츠 협상과 kotlinx.serialization” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 Kotlin Academy 강의 전체를 잠금 해제할 수 있습니다. Kotlin Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“콘텐츠 협상과 kotlinx.serialization”에서 뭘 배우나요?

JSON 직렬화를 구성하고 요청 본문을 자동으로 역직렬화해 보세요. 브라우저에서 직접 실행하는 실습 코드로 Kotlin Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

Kotlin Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 Kotlin Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 3번째 강의입니다.

“콘텐츠 협상과 kotlinx.serialization” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 Kotlin Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 Kotlin Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← Kotlin Academy(으)로 돌아가기