Kotlin Academy · 강의

kotlinx.serialization 설정

플러그인을 추가합니다

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

kotlinx.serialization이란 무엇인가요?

kotlinx.serialization은 객체를 JSON과 같은 형식으로 변환하거나 해당 형식에서 객체로 변환하는 공식 코틀린 라이브러리입니다.

순수 코틀린으로 작성되었으며 멀티플랫폼을 지원합니다
컴파일 시점에 코드를 생성합니다(리플렉션 없음)
JetBrains가 유지 관리합니다

컴파일러 플러그인과 런타임 라이브러리를 함께 사용합니다.

컴파일러 플러그인을 사용하는 이유

리플렉션 기반 라이브러리와 달리 kotlinx.serialization은 직렬화기를 컴파일 시점에 생성합니다.

더 빠르고 런타임 리플렉션 비용이 없습니다
리플렉션이 제한적인 코틀린/네이티브와 JS에서 작동합니다
형식이 안전하며 컴파일러가 검증합니다

따라서 의존성만 추가하는 것이 아니라 kotlin-serialization 플러그인을 적용해야 합니다.

플러그인 적용하기(코틀린 DSL)

build.gradle.kts에서 코틀린 플러그인과 같은 버전으로 직렬화 플러그인을 적용합니다.

plugins {
    kotlin("jvm") version "2.0.0"
    kotlin("plugin.serialization") version "2.0.0"
}

런타임 의존성 추가하기

플러그인은 코드를 생성하지만, JSON 런타임 라이브러리도 필요합니다.

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
}

버전 정렬이 중요한 이유

plugin.serialization 버전은 코틀린 컴파일러 버전과 반드시 일치해야 합니다. 런타임 라이브러리에는 별도의 독립적인 버전이 있습니다.

플러그인 버전 = 코틀린 버전(예: 2.0.0)
런타임 버전은 별도입니다(예: 1.7.1)

플러그인 버전과 코틀린 버전이 일치하지 않으면 원인을 파악하기 어려운 빌드 오류가 발생합니다.

다른 형식

JSON이 가장 일반적이지만, kotlinx.serialization은 추가 아티팩트를 통해 더 많은 형식을 지원합니다:

kotlinx-serialization-json — JSON
kotlinx-serialization-cbor — CBOR 바이너리
kotlinx-serialization-protobuf — 프로토콜 버퍼

필요한 형식의 아티팩트만 추가하면 됩니다.

그루비 DSL에 해당하는 설정

프로젝트에서 코틀린 DSL 대신 그루비 build.gradle을 사용하는 경우 설정은 다음과 같습니다.

// build.gradle (Groovy)
plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.0.0'
    id 'org.jetbrains.kotlin.plugin.serialization' version '2.0.0'
}

dependencies {
    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1'
}

Json 진입점

설정이 끝나면 kotlinx.serialization.json의 Json 객체를 인코딩과 디코딩을 위한 기본 진입점으로 사용합니다.

import kotlinx.serialization.json.Json

val format = Json
// format.encodeToString(...) / format.decodeFromString(...)

최소 동작 코드 조각

플러그인과 런타임을 설정한 후 사용할 수 있는 가장 작은 전체 예제입니다.

import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json

@Serializable
data class City(val name: String, val population: Int)

fun main() {
    val city = City("Istanbul", 15000000)
    val json = Json.encodeToString(city)
    println(json)
}

멀티플랫폼 설정

코틀린 멀티플랫폼 프로젝트에서는 모든 대상이 함께 사용할 수 있도록 런타임을 commonMain에 추가합니다.

sourceSets {
    val commonMain by getting {
        dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
        }
    }
}

일반적인 설정 실수

다음과 같은 자주 발생하는 문제에 주의하세요:

플러그인을 잊으면 Serializer has not been found 오류가 발생합니다
플러그인 버전이 코틀린 버전과 일치하지 않음
런타임은 추가했지만 플러그인은 추가하지 않음(또는 그 반대)
encodeToString 가져오기를 누락함

빠른 확인

kotlinx.serialization에는 왜 Gradle 컴파일러 플러그인이 필요한가요?

복습

다음과 같이 kotlinx.serialization을 설정했습니다:

코틀린 버전에 맞는 kotlin("plugin.serialization") 플러그인 적용
kotlinx-serialization-json 런타임 의존성 추가
Json 객체를 진입점으로 사용

다음에는 모델 클래스에 @Serializable을 지정합니다.

자주 묻는 질문

“kotlinx.serialization 설정” 강의는 무료인가요?

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

“kotlinx.serialization 설정”에서 뭘 배우나요?

플러그인을 추가합니다 브라우저에서 직접 실행하는 실습 코드로 Kotlin Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

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

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

“kotlinx.serialization 설정” 강의는 얼마나 걸리나요?

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

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

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

이 강의의 모든 강의

← Kotlin Academy(으)로 돌아가기