Skip to content

Kotlin serialization 시작하기 ​

직렬화(Serialization)는 객체를 저장하거나 전송한 후 나중에 다시 재구성할 수 있는 형식으로 변환하는 과정입니다.

Kotlin serialization은 다양한 포맷을 지원합니다. 이 튜토리얼에서는 Kotlin serialization에 필요한 플러그인과 종속성을 추가하는 방법과 객체를 JSON 포맷으로 직렬화 및 역직렬화하는 방법을 안내합니다.

플러그인 및 종속성 추가 ​

프로젝트에서 Kotlin serialization을 사용하려면 사용하는 빌드 도구에 따라 해당 플러그인과 종속성 구성을 추가하세요:

kotlin
// build.gradle.kts
plugins {
    kotlin("plugin.serialization") version "2.4.21"
}

dependencies { 
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0")
}
groovy
// build.gradle
plugins {
    id 'org.jetbrains.kotlin.plugin.serialization' version '2.4.21'  
}

dependencies {
    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0'
}
xml
<!-- pom.xml -->
<properties>
    <kotlin.version>2.4.21</kotlin.version>
    <serialization.version>1.11.0</serialization.version>
</properties>

<build>
    <plugins>
        <plugin>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-plugin</artifactId>
            <version>${kotlin.version}</version>
            <executions>
                <execution>
                    <id>compile</id>
                    <phase>compile</phase>
                    <goals>
                        <goal>compile</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <compilerPlugins>
                    <plugin>kotlinx-serialization</plugin>
                </compilerPlugins>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>org.jetbrains.kotlin</groupId>
                    <artifactId>kotlin-maven-serialization</artifactId>
                    <version>${kotlin.version}</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlinx</groupId>
        <artifactId>kotlinx-serialization-json</artifactId>
        <version>${serialization.version}</version>
    </dependency>
</dependencies>

Bazel용 Kotlin 컴파일러 플러그인을 설정하려면 rules_kotlin 저장소의 예제를 참고하세요. Bazel은 Kotlin 팀에서 공식적으로 지원하지 않으며, 해당 저장소는 독립적으로 유지 관리됩니다.

멀티플랫폼 프로젝트에 라이브러리 추가 ​

멀티플랫폼 프로젝트에서 JSON용 Kotlin serialization을 사용하려면 공통 소스 세트(common source set)에 JSON 직렬화 라이브러리 종속성을 추가하세요:

kotlin
commonMain {
    dependencies {
        implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0")
    }
}

이 종속성에는 코어 직렬화 라이브러리도 자동으로 포함됩니다.

Android 프로젝트에서 Kotlin serialization을 위한 R8 구성 ​

Kotlin serialization에는 기본 ProGuard 규칙이 포함되어 있으므로, 코드 축소(shrinking) 후에도 모든 직렬화 가능한 클래스의 직렬화 도구(serializer)를 유지하기 위한 추가 설정이 필요하지 않습니다. 그러나 이 규칙은 이름이 지정된 companion object가 있는 클래스에는 적용되지 않습니다.

이름이 지정된 companion object가 있는 클래스의 serializer를 유지하려면 사용하는 호환 모드(compatibility mode)에 따른 규칙을 proguard-rules.pro 파일에 추가하세요:

bash
# 이름이 지정된 companion object가 있는 클래스의 Serializer는 getDeclaredClasses를 사용하여 검색됩니다.
# 이러한 클래스가 있는 경우 아래 예시를 본인의 클래스로 변경하세요.
-keepattributes InnerClasses # getDeclaredClasses에 필요합니다.

-if @kotlinx.serialization.Serializable class
com.example.myapplication.HasNamedCompanion, # <-- 이름이 지정된 companion을 가진 직렬화 가능 클래스를 나열합니다.
com.example.myapplication.HasNamedCompanion2
{
    static **$* *;
}
-keepnames class <1>$$serializer { # serializer() 호출이 클래스를 올바르게 참조하기 위해 -keepnames로 충분합니다.
    static <1>$$serializer INSTANCE;
}
bash
# 이름이 지정된 companion object가 있는 클래스의 Serializer는 getDeclaredClasses를 사용하여 검색됩니다.
# 이러한 클래스가 있는 경우 아래 예시를 본인의 클래스로 변경하세요.
-keepattributes InnerClasses # getDeclaredClasses에 필요합니다.

-if @kotlinx.serialization.Serializable class
com.example.myapplication.HasNamedCompanion, # <-- 이름이 지정된 companion을 가진 직렬화 가능 클래스를 나열합니다.
com.example.myapplication.HasNamedCompanion2
{
    static **$* *;
}
-keepnames class <1>$$serializer { # serializer() 호출이 클래스를 올바르게 참조하기 위해 -keepnames로 충분합니다.
    static <1>$$serializer INSTANCE;
}

# InnerClasses 속성을 유지하기 위해 serializer 및 직렬화 가능 클래스를 모두 유지합니다.
-keepclasseswithmembers, allowshrinking, allowobfuscation, allowaccessmodification class
com.example.myapplication.HasNamedCompanion, # <-- 이름이 지정된 companion을 가진 직렬화 가능 클래스를 나열합니다.
com.example.myapplication.HasNamedCompanion2
{
    *;
}

더 좁은 범위의 클래스 사양(class specifications)을 사용하는 커스텀 ProGuard 규칙을 적용하여 런타임에 직렬화되지 않는 직렬화 가능 클래스를 제외할 수 있습니다.

객체를 JSON으로 직렬화 ​

Kotlin에서는 kotlinx-serialization-json 라이브러리를 사용하여 객체를 JSON으로 직렬화할 수 있습니다.

클래스를 직렬화 가능하게 만들려면 @Serializable 어노테이션을 지정해야 합니다. 이 어노테이션은 컴파일러에게 해당 클래스의 인스턴스를 직렬화 및 역직렬화하는 데 필요한 코드를 생성하도록 지시합니다. 자세한 내용은 @Serializable 어노테이션을 참고하세요.

예제를 살펴보겠습니다:

  1. 필요한 직렬화 라이브러리에서 선언을 가져옵니다(import):

    kotlin
    import kotlinx.serialization.*
    import kotlinx.serialization.json.*
  2. @Serializable 어노테이션을 추가하여 클래스를 직렬화 가능하게 만듭니다:

    kotlin
    @Serializable
    data class Book(val yearPublished: Int, val title: String)

    @Serializable 어노테이션은 백킹 필드(backing field)가 있는 모든 프로퍼티의 기본 직렬화를 활성화합니다. 프로퍼티 수준의 어노테이션, 선택적(optional) 프로퍼티 등을 사용하여 직렬화 동작을 커스터마이징할 수 있습니다.

    자세한 내용은 클래스 직렬화를 참고하세요.

  3. Json.encodeToString() 함수를 사용하여 이 클래스의 인스턴스를 직렬화합니다:

    kotlin
    // 직렬화 및 JSON 처리 라이브러리에서 선언 가져오기
    import kotlinx.serialization.*
    import kotlinx.serialization.json.*
    
    // Book 클래스를 직렬화 가능하도록 표시
    @Serializable
    data class Book(val yearPublished: Int, val title: String)
    
    fun main() {
        // Book 클래스의 인스턴스를 JSON 문자열로 직렬화
        val json = Json.encodeToString(Book(1937, "The Hobbit"))
        println(json)
        // {"yearPublished":1937,"title":"The Hobbit"}
    }

    결과로 이 객체의 상태를 JSON 포맷으로 담은 문자열({"yearPublished":1937,"title":"The Hobbit"})을 얻을 수 있습니다.

    단일 호출로 객체 컬렉션을 직렬화할 수도 있습니다:

    kotlin
    val bookList = listOf(Book(1937, "The Hobbit"), Book(1867, "War and Peace"))
    val jsonList = Json.encodeToString(bookList)

JSON에서 객체로 역직렬화 ​

역직렬화는 JSON 문자열을 다시 객체로 변환합니다.

Kotlin에서 JSON을 객체로 역직렬화하려면:

  1. 필요한 직렬화 라이브러리에서 선언을 가져옵니다:

    kotlin
    import kotlinx.serialization.*
    import kotlinx.serialization.json.*
  2. @Serializable 어노테이션을 추가하여 클래스를 직렬화 가능하게 만듭니다:

    kotlin
    @Serializable
    data class Book(val yearPublished: Int, val title: String)
  3. Json.decodeFromString() 함수를 사용하여 JSON에서 객체를 역직렬화합니다:

    kotlin
    // 직렬화 및 JSON 처리 라이브러리에서 선언 가져오기
    import kotlinx.serialization.*
    import kotlinx.serialization.json.*
    
    // Book 클래스를 직렬화 가능하도록 표시
    @Serializable
    data class Book(val yearPublished: Int, val title: String)
    
    fun main() {
        // JSON 문자열을 Book 클래스의 인스턴스로 역직렬화
        val obj = Json.decodeFromString<Book>("""{"yearPublished":1937, "title": "The Hobbit"}""")
        println(obj)
        // Book(yearPublished=1937, title=The Hobbit)
    }

축하합니다! Kotlin에서 성공적으로 객체를 JSON으로 직렬화하고, 이를 다시 객체로 역직렬화했습니다.

다음 단계 ​

  • 기본 제공 타입 직렬화에서 기본형(primitives) 및 문자열과 같은 기본 타입과 특정 표준 라이브러리 클래스를 직렬화하는 방법을 알아보세요.
  • 클래스 직렬화에서 클래스 직렬화를 커스터마이징하고 @Serializable 어노테이션의 기본 동작을 조정하는 방법을 살펴보세요.
  • JSON 직렬화 개요에서 JSON 데이터를 처리하고 JSON 직렬화를 구성하는 방법을 더 자세히 알아보세요.