Skip to content

Kotlin 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) 後もすべてのシリアライズ可能クラスのシリアライザーを保持するための追加設定は不要です。 ただし、これらのルールは名前付きコンパニオンオブジェクト(named companion object)を持つクラスには適用されません。

名前付きコンパニオンオブジェクトを持つクラスのシリアライザーを保持するには、使用している互換性モード(compatibility mode) に基づいて、以下のルールを proguard-rules.pro ファイルに追加します。

bash
# 名前付きコンパニオンオブジェクトを持つクラスのシリアライザーは getDeclaredClasses を使用して取得されます
# このようなクラスがある場合は、以下の例をご自身のクラスに置き換えてください
-keepattributes InnerClasses # getDeclaredClasses に必要

-if @kotlinx.serialization.Serializable class
com.example.myapplication.HasNamedCompanion, # <-- 名前付きコンパニオンを持つシリアライズ可能なクラスを列挙
com.example.myapplication.HasNamedCompanion2
{
    static **$* *;
}
-keepnames class <1>$$serializer { # serializer() 呼び出しがクラスを正しく参照できるようにするには -keepnames で十分です
    static <1>$$serializer INSTANCE;
}
bash
# 名前付きコンパニオンオブジェクトを持つクラスのシリアライザーは getDeclaredClasses を使用して取得されます
# このようなクラスがある場合は、以下の例をご自身のクラスに置き換えてください
-keepattributes InnerClasses # getDeclaredClasses に必要

-if @kotlinx.serialization.Serializable class
com.example.myapplication.HasNamedCompanion, # <-- 名前付きコンパニオンを持つシリアライズ可能なクラスを列挙
com.example.myapplication.HasNamedCompanion2
{
    static **$* *;
}
-keepnames class <1>$$serializer { # serializer() 呼び出しがクラスを正しく参照できるようにするには -keepnames で十分です
    static <1>$$serializer INSTANCE;
}

# InnerClasses 属性を保持するために、シリアライザーとシリアライズ可能クラスの両方を保持
-keepclasseswithmembers, allowshrinking, allowobfuscation, allowaccessmodification class
com.example.myapplication.HasNamedCompanion, # <-- 名前付きコンパニオンを持つシリアライズ可能なクラスを列挙
com.example.myapplication.HasNamedCompanion2
{
    *;
}

より絞り込んだクラス指定(class specifications) を持つカスタム ProGuard ルールを使用することで、実行時に一度もシリアライズされないシリアライズ可能クラスを除外できます。

オブジェクトを JSON にシリアライズする ​

Kotlin では、kotlinx-serialization-json ライブラリを使用してオブジェクトを JSON にシリアライズできます。

クラスをシリアライズ可能にするには、@Serializable アノテーションを付加する必要があります。 このアノテーションは、そのクラスのインスタンスをシリアライズおよびデシリアライズするために必要なコードを生成するようコンパイラーに指示します。 詳細については、@Serializable アノテーション を参照してください。

例を見てみましょう。

  1. 必要なシリアライゼーションライブラリから宣言をインポートします。

    kotlin
    import kotlinx.serialization.*
    import kotlinx.serialization.json.*
  2. クラスに @Serializable アノテーションを付加して、シリアライズ可能にします。

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

    @Serializable アノテーションを使用すると、バッキングフィールドを持つすべてのプロパティのデフォルトのシリアライゼーションが有効になります。 プロパティレベルのアノテーションやオプショナルなプロパティなどを使用して、シリアライゼーションの動作をカスタマイズできます。

    詳細については、クラスのシリアライズ を参照してください。

  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"} が得られます。

    1回の呼び出しでオブジェクトのコレクションをシリアライズすることもできます。

    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 にシリアライズし、それを再びオブジェクトにデシリアライズすることができました。

次のステップ ​

  • プリミティブや文字列などの基本型、および特定の標準ライブラリクラスをシリアライズする方法については、組み込み型のシリアライズ を参照してください。
  • クラスのシリアライゼーションをカスタマイズし、@Serializable アノテーションのデフォルトの動作を調整する方法については、クラスのシリアライズ を参照してください。
  • JSON データの扱い方や JSON シリアライゼーションの設定の詳細については、JSON シリアライゼーションの概要 を参照してください。