Kotlin Serialization導入時に詰まったポイント

はじめに

Kotlin Serializationを新規Projectに追加した際に、漏れていて調べることになった部分について紹介します。

Kotlin Serializationとは

Kotlin Serialization is a cross-platform and multi-format framework for data serialization—converting trees of objects to strings, byte arrays, or other serial representations and back. Kotlin Serialization fully supports and enforces the Kotlin type system, making sure only valid objects can be deserialized.

Kotlin Serializationは、データシリアライゼーションのためのクロスプラットフォームおよびマルチフォーマットフレームワークであり、オブジェクトのツリーを文字列、バイト配列、または他のシリアル表現に変換して戻します。Kotlin SerializationはKotlinの型システムを完全にサポートし、強制するため、有効なオブジェクトだけがデシリアライズできます。(DeepL翻訳)

その他にJSONパーサー機能を提供してくれるライブラリとしては、GsonやMoshiがあります。

Gsonは今ではGson is deprecated.が有名ですね。MoshiはそのReplace先としてよく利用されていた印象です。
Kotlin SerializationはMultiplatformに対応しているフレームワークであることや、Navigation 2.8.0-alpha08において、Kotlin Serializationを使ってJetpack Composeで型安全なナビゲーションが可能になったことからも、多くのエンジニアが採用するシリアリゼーションライブラリと言えそうです。
直近ではsavedstate1.3.0-alpha05でSavedStateもサポートするようになり、活用の幅が広がっています。

導入方法

今回はVersion Catalogでの導入方法を紹介します

serialization pluginの設定

gradle/libs.versions.toml

[versions]
kotlin = "2.0.20"

[plugins]
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

app/build.gradle.kts

plugins {
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.serialization)
}

JSON ライブラリへの依存関係の追加

• 使用しているKotlinのVersionと、追加しようとしているKotlin SerializationのVersionに問題ないかはReleasesで確認してください

gradle/libs.versions.toml

[versions]
kotlinxSerialization = "1.7.3"

app/build.gradle.kts

dependencies {
    implementation("libs.kotlinx.serialization.json")
}

[補足]
インターネットに接続し、APIを叩けるようにする場合、Kotlin Serializationと同時に導入するライブラリとしてRetrofitがあると思います。

Get data from the internet (CodeLab)ではRetrofitと連携するサードパーティライブラリとして、Kotlin Serialization Converterが紹介されています(執筆時点)。
このライブラリはRetrofit2.10.0にて取り込まれ、Public archiveになっているため導入は不要です。

デフォルト引数を指定したdata classがうまくSerializeされない

想定される状況

• APIのレスポンス/リクエストBodyに特定の引数が含まれておらず、200が返ってこない

結論

デフォルト引数は、デフォルトではJSONにエンコードされないため

JsonにencodeDefaultsをtrueに設定するか、

val format = Json { encodeDefaults = true }

@Serializable
class Project(
    val name: String,
    val language: String = "Kotlin",
    val website: String? = null
)

fun main() {
    val data = Project("kotlinx.serialization")
    println(format.encodeToString(data))
}

@EncodeDefaultをつけることでエンコード対象にできます。

@Serializable
@OptIn(ExperimentalSerializationApi::class)
data class Project(
    val name: String,
    @EncodeDefault val language: String = "Kotlin"
)

デフォルト値を毎回シリアライズ対象することで、データサイズが大きくなるのを防ぐための設定です。
特に、デフォルト値がnullに設定されている場合に、対応するプロパティへの書き込みを回避できます。
本当にデフォルト引数として含めなくてはならないパラメーターかどうか、要件に沿って検討してください。

補足

EncodeDefault.Modeパラメータを利用して、上記の設定等がされていても、エンコード対象から外す設定にすることもできます。

@Serializable
@OptIn(ExperimentalSerializationApi::class
data class User(
    val name: String,
    @EncodeDefault(EncodeDefault.Mode.NEVER) val projects: List<Project> = emptyList()
)

難読化を有効にしたビルドが失敗する

エラー

kotlinx.serialization.SerializationException: Serializer for class '...' is not found. 
Please ensure that class is Mark as '@Serializable' and that serialization compiler plugin is applied.

結論

• proguard-rules.proファイルで@Serializableがついたクラスを難読化対象から外す
  • README
  • Serialization with proguard

app/proguard-rules.pro

-keep, allowobfuscation, allowoptimization, allowaccessmodification @kotlinx.serialization.Serializable class *

補足

各設定項目は以下のような役割があります。詳細はProGuard manualを確認してください。

• Keep Options

  • -keep
    • 指定したクラスやクラスメンバーを難読化対象から除外する

• Keep Option Modifiers

  • allowoptimization
    • -keepオプションで指定したクラス、メソッド等に対して最適化処理を許可する
  • allowobfuscation
    • -keepオプションで指定したクラス、メソッド等に対し難読化処理を許可する

• Optimization Options

  • allowaccessmodification
    • 最適化処理中に、各クラスやメンバー変数のアクセス修飾子を拡張する
      • 最適化ステップの結果を改善する可能性がある
      • ライブラリとして使用されるコードに対して最適化をする場合は、本オプションを指定しないほうが良い

まとめ

公式ドキュメントに全部書いているから、隅々読もうね！