Kotlin Serialization入門：JSONデータ変換の基本

// JSON配列からStringのリストにデシリアライズ
val jsonStringList = """["Kotlin","Serialization","JSON"]"""
val tagList = Json.decodeFromString<List<String>>(jsonStringList) // 型引数 <List<String>> が必要
println("Tag list: $tagList")
// 出力: Tag list: [Kotlin, Serialization, JSON]

// ジェネリック型を持つコレクションの場合、serializer を明示的に指定することもできます（通常は推論で十分ですが、複雑なケースで必要になることがあります）。
// val tagListExplicit = Json.decodeFromString(ListSerializer(String.serializer()), jsonStringList)
// println("Tag list (explicit): $tagListExplicit")

}
“`

コレクションをデシリアライズする場合も、デシリアライズ先の型を正確に指定することが重要です。List<String> のように、要素の型も含めて指定します。

例：Nullableプロパティのデシリアライズ

Nullableプロパティを持つクラスへのデシリアライズは、JSON文字列にそのキーが存在するかどうかによって挙動が変わります。

“`kotlin
import kotlinx.serialization.json.Json
import kotlinx.serialization.Serializable
import kotlinx.serialization.decodeFromString

@Serializable
data class Person(val name: String, val email: String?)

fun main() {
val jsonWithEmail = “””{“name”:”Bob”,”email”:”[email protected]”}”””
val personWithEmail = Json.decodeFromString(jsonWithEmail)
println(“Person with email: Name=${personWithEmail.name}, Email=${personWithEmail.email}”)
// 出力: Person with email: Name=Bob, [email protected]

val jsonWithoutEmail = """{"name":"Charlie"}""" // emailキーが存在しない
val personWithoutEmail = Json.decodeFromString<Person>(jsonWithoutEmail)
println("Person without email: Name=${personWithoutEmail.name}, Email=${personWithoutEmail.email}")
// 出力: Person without email: Name=Charlie, Email=null // emailプロパティはnullになる

val jsonWithExplicitNullEmail = """{"name":"David","email":null}""" // emailキーがnull
 val personWithExplicitNullEmail = Json.decodeFromString<Person>(jsonWithExplicitNullEmail)
println("Person with explicit null email: Name=${personWithExplicitNullEmail.name}, Email=${personWithExplicitNullEmail.email}")
// 出力: Person with explicit null email: Name=David, Email=null // emailプロパティはnullになる

}
“`

JSON文字列にキーが存在しない場合、またはキーの値が null である場合、Kotlin Serializationは対応するnullableプロパティを null にデシリアライズします。これにより、JSONデータの欠落に対して堅牢なコードを書くことができます。非nullableなプロパティに対応するキーがJSONに存在しない場合は、デシリアライズ時にエラーが発生します（これについては後述のエラーハンドリングで詳しく説明します）。

Serializer の取得方法

encodeToString や decodeFromString メソッドは、通常、型のシリアライザーを自動的に推論してくれます。しかし、ジェネリック型を持つ複雑なケース（例: List<MyCustomClass>, Map<String, AnotherClass>) や、ジェネリック型のパラメータを持つクラスの場合、シリアライザーを明示的に指定する必要があることがあります。

これには serializer<T>() 関数を使用します。

“`kotlin
import kotlinx.serialization.KSerializer
import kotlinx.serialization.builtins.ListSerializer
import kotlinx.serialization.builtins.serializer
import kotlinx.serialization.json.Json
import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.decodeFromString

@Serializable
data class Item(val id: Int, val name: String)

fun main() {
val itemList = listOf(Item(1, “A”), Item(2, “B”))

// List<Item> のシリアライザーを取得
val itemListSerializer: KSerializer<List<Item>> = ListSerializer(Item.serializer())

// 明示的にシリアライザーを指定してシリアライズ
val jsonStringList = Json.encodeToString(itemListSerializer, itemList)
println(jsonStringList)
// 出力: [{"id":1,"name":"A"},{"id":2,"name":"B"}]

// JSON文字列からList<Item>にデシリアライズ
val decodedItemList = Json.decodeFromString(itemListSerializer, jsonStringList)
println(decodedItemList)
// 出力: [Item(id=1, name=A), Item(id=2, name=B)]

// 通常は型推論で十分ですが、明示的に指定する必要がある場合にこの方法を使います。
// val jsonStringListInferred = Json.encodeToString(itemList) // こちらでも動くことが多い
// val decodedItemListInferred = Json.decodeFromString<List<Item>>(jsonStringList) // こちらでも動くことが多い

}
“`

serializer<Item>() は、@Serializable が付与された Item クラスのシリアライザーを返します。ListSerializer(Item.serializer()) は、「要素の型が Item であるリスト」のためのシリアライザーを構築します。このように、組み込みの *Serializer クラスと serializer<T>() 関数を組み合わせて、複雑な型のシリアライザーを取得できます。

これで、基本的なKotlinオブジェクトとJSON文字列の間のシリアライズ・デシリアライズの方法が分かりました。デフォルト設定の Json オブジェクトは多くのケースで機能しますが、JSONの形式が標準的でない場合や、特定の挙動をカスタマイズしたい場合があります。次に、Json オブジェクトの高度な設定オプションについて見ていきましょう。

高度な設定とカスタマイズ

Kotlin Serializationの Json オブジェクトは、様々なオプションを提供しており、JSONの出力形式を調整したり、デシリアライズ時の挙動を変更したりできます。これらのオプションは、Json オブジェクトをインスタンス化する際にコンストラクタの引数として指定します。

“`kotlin
import kotlinx.serialization.json.Json

val customJson = Json {
// ここにカスタマイズオプションを記述
prettyPrint = true // 例えば、整形されたJSONを出力する
ignoreUnknownKeys = true // 例えば、JSONに未知のキーがあっても無視する
// … 他のオプション
}
“`

よく使われる、かつ基本的な範囲で重要なオプションをいくつか紹介します。

1. prettyPrint: Boolean (デフォルト: false)

   • JSON文字列を人間が読みやすいように、インデントや改行を付けて整形して出力します。開発中のデバッグ時などに非常に便利です。
   • true に設定すると、シリアライズ時の出力が見やすくなります。

   “`kotlin
   import kotlinx.serialization.json.Json
   import kotlinx.serialization.Serializable
   import kotlinx.serialization.encodeToString

   @Serializable
   data class User(val name: String, val age: Int)

   fun main() {
   val user = User(“Alice”, 30)

   // デフォルト設定 (整形されない)
   println("Default: ${Json.encodeToString(user)}")
   // 出力例: Default: {"name":"Alice","age":30}
   
   // prettyPrint = true に設定
   val prettyJson = Json { prettyPrint = true }
   println("Pretty: ${prettyJson.encodeToString(user)}")
   // 出力例:
   // Pretty: {
   //   "name": "Alice",
   //   "age": 30
   // }
   

   }
   “`

2. ignoreUnknownKeys: Boolean (デフォルト: false)

   • デシリアライズ時に、対応するKotlinクラスのプロパティに存在しないキーがJSON文字列に含まれていた場合、その未知のキーを無視するかどうかを制御します。
   • false の場合（デフォルト）、未知のキーが見つかると UnknownKeyException が発生します。これは、JSONスキーマの変更に気付かずに古いデータ構造でパースしようとした場合などにエラーとして検知できるため、安全性は高いです。
   • true に設定すると、未知のキーは単にスキップされ、エラーになりません。APIからのレスポンスなど、今後フィールドが増える可能性があるが、現在のクライアントでは不要なフィールドを無視したい場合に便利です。

   “`kotlin
   import kotlinx.serialization.json.Json
   import kotlinx.serialization.Serializable
   import kotlinx.serialization.decodeFromString
   import kotlinx.serialization.SerializationException // エラークラス

   @Serializable
   data class User(val name: String, val age: Int)

   fun main() {
   val jsonWithExtraKey = “””{“name”:”Alice”,”age”:30,”city”:”Tokyo”}””” // cityという未知のキーを含む

   // デフォルト設定 (ignoreUnknownKeys = false)
   try {
       Json.decodeFromString<User>(jsonWithExtraKey)
   } catch (e: SerializationException) {
       println("Default (ignoreUnknownKeys=false) caught exception: ${e.message}")
       // 出力例: Default (ignoreUnknownKeys=false) caught exception: Unknown key 'city'
   }
   
   // ignoreUnknownKeys = true に設定
   val lenientJson = Json { ignoreUnknownKeys = true }
   try {
       val user = lenientJson.decodeFromString<User>(jsonWithExtraKey)
       println("With ignoreUnknownKeys=true: Successfully decoded user: ${user.name}, ${user.age}")
       // 出力例: With ignoreUnknownKeys=true: Successfully decoded user: Alice, 30
   } catch (e: SerializationException) {
       println("This should not happen with ignoreUnknownKeys=true")
   }
   

   }
   “`

3. isLenient: Boolean (デフォルト: false)

   • JSONパース時に、より寛容なモードで解析するかどうかを制御します。
   • false の場合（デフォルト）、JSON標準に厳密に従います。例えば、キーや文字列がダブルクォーテーションで囲まれていない場合、特別なエスケープが必要な文字が含まれている場合などにエラーになります。
   • true に設定すると、キーがクォーテーションされていなかったり、コメントが含まれていたり、特別なエスケープなしで制御文字が使われていたりする、非標準的なJSONでもパースを試みます。設定ファイルなど、手動で編集される可能性のあるJSONを扱う場合に役立つことがありますが、セキュリティリスクを高める可能性もあるため注意が必要です。

   “`kotlin
   import kotlinx.serialization.json.Json
   import kotlinx.serialization.Serializable
   import kotlinx.serialization.decodeFromString
   import kotlinx.serialization.SerializationException

   @Serializable
   data class Item(val name: String)

   fun main() {
   // 非標準的なJSON (キーがクォーテーションされていない)
   val malformedJson = “””{ name: “Laptop” }”””

   // デフォルト設定 (isLenient = false)
   try {
       Json.decodeFromString<Item>(malformedJson)
   } catch (e: SerializationException) {
       println("Default (isLenient=false) caught exception: ${e.message}")
       // 出力例: Default (isLenient=false) caught exception: Unexpected JSON token at offset 2: Expected quotation mark '"', but had 'n' instead
   }
   
   // isLenient = true に設定
   val lenientJson = Json { isLenient = true }
   try {
       val item = lenientJson.decodeFromString<Item>(malformedJson)
       println("With isLenient=true: Successfully decoded item: ${item.name}")
       // 出力例: With isLenient=true: Successfully decoded item: Laptop
   } catch (e: SerializationException) {
       println("This should not happen with isLenient=true")
   }
   

   }
   “`

4. encodeDefaults: Boolean (デフォルト: false)

   • シリアライズ時に、プロパティの値がデータクラスで定義されたデフォルト値と等しい場合に、そのプロパティをJSON出力に含めるかどうかを制御します。
   • false の場合（デフォルト）、デフォルト値と同じプロパティはJSONから省略されます。これによりJSONがコンパクトになります。
   • true に設定すると、デフォルト値と同じプロパティも含めて、すべてのプロパティがJSONに出力されます。
   • @EncodeDefault アノテーションは、この設定よりも優先されます。@EncodeDefault は特定のプロパティに対して常にエンコードすることを強制し、encodeDefaults = true は @EncodeDefault が付いていないすべてのプロパティに対してデフォルト値でもエンコードすることを強制します。

   “`kotlin
   import kotlinx.serialization.json.Json
   import kotlinx.serialization.Serializable
   import kotlinx.serialization.encodeToString
   import kotlinx.serialization.EncodeDefault

   @Serializable
   data class Config(
   val timeout: Int = 5000, // デフォルト値あり
   @EncodeDefault
   val retries: Int = 3, // デフォルト値あり + EncodeDefault
   val verbose: Boolean = false // デフォルト値あり
   )

   fun main() {
   val defaultConfig = Config() // すべてデフォルト値

   // デフォルト設定 (encodeDefaults = false)
   println("Default Json: ${Json.encodeToString(defaultConfig)}")
   // 出力例: Default Json: {"retries":3} // timeoutとverboseはデフォルト値なので省略、retriesは@EncodeDefaultで出力
   
   // encodeDefaults = true に設定
   val jsonWithDefaults = Json { encodeDefaults = true }
   println("Json with encodeDefaults=true: ${jsonWithDefaults.encodeToString(defaultConfig)}")
   // 出力例: Json with encodeDefaults=true: {"timeout":5000,"retries":3,"verbose":false} // すべて出力される
   

   }
   “`

   通常、encodeDefaults = false (デフォルト) でJSONをコンパクトに保つのが一般的です。特定のプロパティを常に含めたい場合にのみ @EncodeDefault を使用します。

5. explicitNulls: Boolean (デフォルト: true in 1.3.0+, false before)

   • シリアライズ時に、nullableなプロパティの値が null である場合に、JSON出力に "key": null の形式で明示的に含めるかどうかを制御します。
   • デフォルトは true です（バージョン1.3.0以降）。つまり、nullableなプロパティが null の場合、デフォルトでは "key": null として出力されます。
   • false に設定すると、nullableなプロパティが null の場合、そのキーはJSON出力から省略されます。

   “`kotlin
   import kotlinx.serialization.json.Json
   import kotlinx.serialization.Serializable
   import kotlinx.serialization.encodeToString

   @Serializable
   data class Contact(val name: String, val email: String?, val phone: String?)

   fun main() {
   val contact = Contact(“Alice”, null, “123-4567”)

   // デフォルト設定 (explicitNulls = true)
   println("Default Json: ${Json.encodeToString(contact)}")
   // 出力例: Default Json: {"name":"Alice","email":null,"phone":"123-4567"} // emailがnullでも明示的に出力
   
   // explicitNulls = false に設定
   val jsonWithoutNulls = Json { explicitNulls = false }
   println("Json with explicitNulls=false: ${jsonWithoutNulls.encodeToString(contact)}")
   // 出力例: Json with explicitNulls=false: {"name":"Alice","phone":"123-4567"} // nullのemailは省略される
   

   }
   “`

   JSON APIの仕様によっては、null値を明示的に出力する必要がある場合（"key": null）と、単にキーを省略する必要がある場合（キーなし）があります。このオプションでその挙動を制御できます。デフォルトの true は、デシリアライズ時にキーの存在/非存在とnull値の区別が必要な場合に役立ちますが、JSONが冗長になることもあります。API仕様に合わせて選択してください。

これらのオプションを適切に組み合わせることで、様々なJSON形式に対応したり、開発効率を上げたりすることができます。

@SerialName アノテーション

Kotlinクラスのプロパティ名とJSONのキー名が異なる場合があります。例えば、Kotlinではキャメルケース (userName) を使うことが多いですが、JSONではスネークケース (user_name) が使われることがあります。このような場合に、@SerialName アノテーションを使ってマッピングを定義できます。

“`kotlin
import kotlinx.serialization.json.Json
import kotlinx.serialization.Serializable
import kotlinx.serialization.SerialName
import kotlinx.serialization.encodeToString
import kotlinx.serialization.decodeFromString

@Serializable
data class UserProfile(
@SerialName(“user_id”) // JSONキーは “user_id” だが、プロパティ名は userId
val userId: Int,
@SerialName(“user_name”) // JSONキーは “user_name” だが、プロパティ名は userName
val userName: String,
val age: Int // このプロパティはKotlin名と同じキー (age) を使用
)

fun main() {
val profile = UserProfile(101, “Alice”, 30)

// シリアライズ: Kotlinのプロパティ名 -> JSONのキー名に変換
val jsonString = Json.encodeToString(profile)
println(jsonString)
// 出力: {"user_id":101,"user_name":"Alice","age":30} // 指定したJSONキー名で出力される

// デシリアライズ: JSONのキー名 -> Kotlinのプロパティ名に変換
val jsonInput = """{"user_id":202,"user_name":"Bob","age":25}"""
val decodedProfile = Json.decodeFromString<UserProfile>(jsonInput)
println("Decoded Profile: userId=${decodedProfile.userId}, userName=${decodedProfile.userName}, age=${decodedProfile.age}")
// 出力: Decoded Profile: userId=202, userName=Bob, age=25 // 指定したJSONキー名からKotlinのプロパティ名にデシリアライズされる

}
“`

@SerialName("...") をプロパティに付与することで、そのプロパティに対応するJSONキーの名前を指定できます。このアノテーションはシリアライズ時とデシリアライズ時の両方に影響します。Kotlin側の名前を変更せずにJSON側の名前だけを変えたい場合に非常に便利です。

@Transient アノテーション

特定のプロパティをシリアライズ/デシリアライズの対象から除外したい場合があります。例えば、一時的な計算結果、セキュリティ上JSONに含めたくない情報、あるいはシリアライズできない型のプロパティなどです。これには @Transient アノテーションを使用します。

@Transient を付与したプロパティは、シリアライズ時には無視され、JSON出力に含まれません。デシリアライズ時には、このプロパティは対象外となるため、データクラスのコンストラクタでデフォルト値が設定されているか、あるいは lateinit や nullable 型など、値が設定されなくてもオブジェクトの構築が可能な方法で定義されている必要があります。デフォルト値を使用するのが最も簡単です。

“`kotlin
import kotlinx.serialization.json.Json
import kotlinx.serialization.Serializable
import kotlinx.serialization.Transient // Transient はこのパッケージにあります
import kotlinx.serialization.encodeToString
import kotlinx.serialization.decodeFromString

@Serializable
data class UserData(
val id: Int,
val name: String,
@Transient // このプロパティはシリアライズ/デシリアライズから除外
val isAuthenticated: Boolean = false, // @Transient プロパティにはデフォルト値が必要
@Transient
val temporaryToken: String? = null // nullable型でもデフォルト値があればOK
)

fun main() {
val userData = UserData(1, “Alice”, true, “temp-abc”) // isAuthenticatedとtemporaryTokenに値を設定

// シリアライズ: @Transient が付いたプロパティは出力されない
val jsonString = Json.encodeToString(userData)
println(jsonString)
// 出力: {"id":1,"name":"Alice"} // isAuthenticatedとtemporaryTokenは含まれない

// デシリアライズ: @Transient が付いたプロパティはデシリアライズされず、デフォルト値が設定される
val jsonInput = """{"id":2,"name":"Bob"}""" // isAuthenticatedとtemporaryTokenのキーは含まれない
val decodedUserData = Json.decodeFromString<UserData>(jsonInput)
println("Decoded UserData: id=${decodedUserData.id}, name=${decodedUserData.name}, isAuthenticated=${decodedUserData.isAuthenticated}, temporaryToken=${decodedUserData.temporaryToken}")
// 出力: Decoded UserData: id=2, name=Bob, isAuthenticated=false, temporaryToken=null // デフォルト値が設定される

}
“`

@Transient プロパティには必ずデフォルト値を設定してください。そうしないと、デシリアライズ時にそのプロパティに値を設定する方法がなくなり、エラーとなる可能性があります。

これらの高度な設定とアノテーションを使いこなすことで、Kotlin Serializationは様々なJSONフォーマットに対応し、より柔軟で実用的なデータ変換を実現できます。

エラーハンドリング

JSONデータのパースやシリアライズ時には、様々な理由でエラーが発生する可能性があります。例えば、入力されたJSON文字列の形式が不正である、デシリアライズしようとしているKotlinクラスの構造とJSONの構造が一致しない、必須フィールドがJSONに存在しない、値の型が期待と異なるなどです。

Kotlin Serializationは、これらのエラーを検出すると kotlinx.serialization.SerializationException またはそのサブクラスをスローします。適切なエラーハンドリングを行うことで、アプリケーションの安定性を高めることができます。

一般的なエラーとその対処法をいくつか紹介します。

1. 形式不正なJSON文字列

   • 入力されたJSON文字列の構文が正しいJSON形式としてパースできない場合に発生します。
   • 例: 括弧の対応が取れていない、キーや文字列が適切にクォーテーションされていないなど。
   • 例外: JsonDecodingException (多くの場合、SerializationException のサブクラス)
   • 対処法:
     • try-catch ブロックで例外を捕捉する。
     • isLenient = true オプションで、より寛容なパースを試みる（ただし非推奨の場合あり）。
     • JSON文字列がどこから来るのかを確認し、ソース側で正しいJSON形式を保証する。

   “`kotlin
   import kotlinx.serialization.json.Json
   import kotlinx.serialization.Serializable
   import kotlinx.serialization.decodeFromString
   import kotlinx.serialization.SerializationException

   @Serializable
   data class Item(val name: String)

   fun main() {
   // 不正なJSON形式
   val badJson = “””{“name”: “Laptop”””” // 最後の } が欠けている

   try {
       val item = Json.decodeFromString<Item>(badJson)
       println("Decoded: ${item.name}")
   } catch (e: SerializationException) {
       println("Error decoding JSON: ${e.message}")
       // 出力例: Error decoding JSON: Unexpected end of input at offset 20: Expected closing brace '}'
   }
   

   }
   “`

2. 必須プロパティの欠落

   • デシリアライズ先のKotlinクラスで非nullableとして定義されているプロパティに対応するキーが、入力JSONに存在しない場合に発生します。
   • 例外: MissingFieldException (多くの場合、SerializationException のサブクラス)
   • 対処法:
     • try-catch ブロックで例外を捕捉する。
     • JSONを提供する側に、必須フィールドを常に含めるように修正を依頼する。
     • Kotlin側のプロパティ定義を見直し、もしそのフィールドが常に必須ではないのであれば、nullable (?) に変更する。
     • プロパティにデフォルト値を設定する。

   “`kotlin
   import kotlinx.serialization.json.Json
   import kotlinx.serialization.Serializable
   import kotlinx.serialization.decodeFromString
   import kotlinx.serialization.SerializationException

   @Serializable
   data class Product(val id: Int, val name: String) // nameは非nullable

   fun main() {
   // name キーが欠落しているJSON
   val jsonWithoutName = “””{“id”: 1}”””

   try {
       val product = Json.decodeFromString<Product>(jsonWithoutName)
       println("Decoded: ${product.id}, ${product.name}")
   } catch (e: SerializationException) {
       println("Error decoding JSON: ${e.message}")
       // 出力例: Error decoding JSON: Field 'name' is required for type with serial name 'Product', but it was missing
   }
   
   // 対処法例：nameをnullableにするかデフォルト値を追加
   @Serializable
   data class ProductFixed(val id: Int, val name: String? = null) // nameをnullableにしてデフォルト値を設定
   
   try {
       val product = Json.decodeFromString<ProductFixed>(jsonWithoutName)
       println("Decoded (fixed): ${product.id}, ${product.name}")
       // 出力: Decoded (fixed): 1, null
   } catch (e: SerializationException) {
        println("This should not happen")
   }
   

   }
   “`

3. 未知のキー

   • 入力JSONに、デシリアライズ先のKotlinクラスに存在しないキーが含まれている場合に発生します。
   • 例外: UnknownKeyException (デフォルト設定 ignoreUnknownKeys = false の場合)
   • 対処法:
     • try-catch ブロックで例外を捕捉する。
     • ignoreUnknownKeys = true オプションを設定して、未知のキーを無視する。APIレスポンスなど、今後フィールドが増える可能性がある場合に有効です。
     • Kotlinクラスに、未知のキーに対応するプロパティを追加する（ただし、これはJSONスキーマに厳密に従う場合に限られます）。

   “`kotlin
   import kotlinx.serialization.json.Json
   import kotlinx.serialization.Serializable
   import kotlinx.serialization.decodeFromString
   import kotlinx.serialization.SerializationException

   @Serializable
   data class User(val name: String, val age: Int)

   fun main() {
   // address キーが未知のキー
   val jsonWithUnknownKey = “””{“name”:”Alice”,”age”:30,”address”:”Tokyo”}”””

   // デフォルト設定 (ignoreUnknownKeys = false)
   try {
       Json.decodeFromString<User>(jsonWithUnknownKey)
   } catch (e: SerializationException) {
       println("Error decoding JSON: ${e.message}")
       // 出力例: Error decoding JSON: Unknown key 'address'
   }
   
   // ignoreUnknownKeys = true に設定
   val lenientJson = Json { ignoreUnknownKeys = true }
   try {
       val user = lenientJson.decodeFromString<User>(jsonWithUnknownKey)
       println("Decoded with ignoreUnknownKeys=true: ${user.name}, ${user.age}")
       // 出力: Decoded with ignoreUnknownKeys=true: Alice, 30
   } catch (e: SerializationException) {
       println("This should not happen")
   }
   

   }
   “`

4. 型不一致

   • 入力JSONの値の型が、対応するKotlinプロパティの型と一致しない場合に発生します。例えば、数値型プロパティに対してJSONで文字列が送られてきた場合などです。
   • 例外: JsonDecodingException (多くの場合、SerializationException のサブクラス)
   • 対処法:
     • try-catch ブロックで例外を捕捉する。
     • JSONを提供する側に、正しい型で値を送信するように修正を依頼する。
     • Kotlin側のプロパティ型を見直し、JSONで送られてくる可能性のある型（例: 数値が文字列として送られてくるなら String 型として受け取る）に対応できるように変更し、その後の処理で型変換を行う。

   “`kotlin
   import kotlinx.serialization.json.Json
   import kotlinx.serialization.Serializable
   import kotlinx.serialization.decodeFromString
   import kotlinx.serialization.SerializationException

   @Serializable
   data class Product(val id: Int, val price: Double)

   fun main() {
   // price が文字列として送られているJSON
   val jsonWithTypeMismatch = “””{“id”: 1, “price”: “19.99”}””” // price は Double を期待している

   try {
       val product = Json.decodeFromString<Product>(jsonWithTypeMismatch)
       println("Decoded: ${product.id}, ${product.price}")
   } catch (e: SerializationException) {
       println("Error decoding JSON: ${e.message}")
       // 出力例: Error decoding JSON: Unexpected JSON token at offset 17: Expected FLOAT or DOUBLE, but found STRING instead
   }
   
   // 対処法例：priceをStringとして受け取る
   @Serializable
   data class ProductFixed(val id: Int, val price: String) // priceをStringとして受け取る
   
   try {
       val product = Json.decodeFromString<ProductFixed>(jsonWithTypeMismatch)
       val priceAsDouble = product.price.toDoubleOrNull() // 手動でDoubleに変換
       println("Decoded (fixed): ${product.id}, ${product.price} -> Double: $priceAsDouble")
       // 出力: Decoded (fixed): 1, 19.99 -> Double: 19.99
   } catch (e: SerializationException) {
        println("This should not happen")
   }
   

   }
   “`

デシリアライズ処理は、外部からの入力（JSON文字列）を扱うため、様々な不正なデータが送られてくる可能性があります。これらのエラーケースを想定し、try-catch ブロックを使って例外を捕捉し、適切に処理（ログ出力、デフォルト値の使用、エラーメッセージの表示など）を行うことが、堅牢なアプリケーションを構築する上で非常に重要です。

また、前述の Json オブジェクトのオプション（特に ignoreUnknownKeys や isLenient）は、エラー発生を防ぐための設定としても利用できます。ただし、これらのオプションはエラーを「無視」する可能性があるため、本来検出されるべき問題を見逃さないよう、慎重に使用する必要があります。基本的には、厳密なパース設定 (ignoreUnknownKeys = false, isLenient = false) でエラーを検出し、必要に応じて例外ハンドリングやJSON/Kotlinクラス定義の見直しで対応するのがおすすめです。

Kotlin Serializationの利点

ここまでKotlin Serializationの基本的な使い方とカスタマイズ、エラーハンドリングを見てきました。改めて、Kotlin Serializationが提供する主な利点をまとめます。

1. Kotlinネイティブな設計:

   • データクラス、null安全性、コルーチンなど、Kotlin言語の特性を活かした設計になっています。これにより、Kotlinらしい簡潔で安全なコードでJSON変換を記述できます。特にnull安全性のサポートは、デシリアライズ時のエラーを減らす上で強力です。
   • コンパイル時のコード生成により、リフレクションを使用しません。これにより、Kotlin/Nativeのようなリフレクションが制限される環境でも動作し、マルチプラットフォーム開発に適しています。

2. コンパイル時の安全性:

   • @Serializable アノテーションが付与されたクラスは、コンパイル時にシリアライズ可能かどうかがチェックされます。サポートされていない型を使っている場合や、@Transient にデフォルト値がない場合など、多くの問題をコンパイル段階で検出できるため、実行時エラーを未然に防ぎやすくなります。

3. マルチプラットフォーム対応:

   • JVM、JS、Nativeの各プラットフォームで共通のシリアライズロジックを使用できます。これにより、共通コードでデータモデルを定義し、異なるプラットフォーム間でデータをやり取りする処理を効率的に実装できます。

4. パフォーマンス:

   • リフレクションを使用せず、コンパイル時に生成された専用コードを使うため、一般的にJacksonやGsonなどのリフレクションベースのライブラリよりも高速なシリアライズ・デシリアライズ処理が期待できます。

5. 柔軟なカスタマイズ性:

   • Json オブジェクトの豊富なオプションにより、JSONの出力形式やデシリアライズ時の挙動を細かく制御できます。
   • @SerialName、@Transient などのアノテーションにより、Kotlinのプロパティ名とJSONキー名のマッピングや、プロパティの除外を柔軟に行えます。
   • カスタムシリアライザー/デシリアライザーを記述することで、標準でサポートされていない型（例: java.time.LocalDateTime など）や、特殊な形式のデータも扱うことができます（この記事では詳細を割愛しましたが、高度な機能として提供されています）。

6. 統一されたAPI:

   • JSONだけでなく、CBOR、Protocol Buffers、Propertiesなどの様々なデータフォーマットに対して、共通のシリアライズ/デシリアライズAPI (encodeToString, decodeFromString など) を使用できます。これにより、フォーマットが変わっても学習コストやコードの変更量を抑えることができます。

これらの利点から、Kotlin Serializationは特にKotlinプロジェクトにおいて、JSON変換ライブラリとして非常に魅力的な選択肢となります。

他のライブラリとの比較 (Jackson, Gsonなど)

Kotlin Serialization以外にも、Javaの世界で広く使われているJSONライブラリ（Jackson, Gson, Moshiなど）をKotlinプロジェクトで使用することは可能です。これらのライブラリもKotlin対応を進めていますが、Kotlin Serializationと比較した場合の主な違いを理解しておくことは、どのライブラリを選択するかを判断する上で役立ちます。

Kotlin Serializationを選ぶべきケース:

• 新しいKotlinプロジェクトを開始する場合。
• マルチプラットフォーム開発を行っており、異なるプラットフォーム間でデータモデルを共有したい場合。
• Null安全性やImmutableなデータクラスを厳密に扱いたい場合。
• コンパイル時の安全性を重視し、実行時エラーを減らしたい場合。
• JSON以外のフォーマット（CBOR, Protocol Buffersなど）も将来的に扱う可能性がある場合。

既存のJackson/Gsonプロジェクトで使い続けるケース:

• 既に大規模なJackson/Gsonベースのコードがあり、移行コストが大きい場合。
• JacksonやGsonが提供する特定の高度な機能（例: 特定のデータソースへの直接連携、複雑なカスタムシリアライザーなど）に依存している場合。
• Javaコードとの相互運用性が非常に重要で、共通のライブラリを使用したい場合。
• エコシステムの成熟度や、特定のフレームワークとの連携を重視する場合。

最近のJacksonやGsonはKotlinモジュールや拡張を提供しており、以前に比べてKotlinとの親和性は向上しています。しかし、Kotlin Serializationは最初からKotlinのために設計されているため、Kotlin言語のメリットを最大限に引き出せる点が大きな強みです。

特にこれからKotlinで新規プロジェクトを始める場合や、既存のプロジェクトでもJSON変換部分をクリーンに保ちたい場合は、Kotlin Serializationを積極的に検討する価値は十分にあります。

まとめ

この記事では、Kotlin Serializationライブラリを用いたJSONデータ変換の基本的な方法について、プロジェクトへの導入から、シリアライズ可能なクラスの定義、実際の変換処理、そして便利なカスタマイズオプションやエラーハンドリングまで、詳細に解説しました。

学んだ主要なポイントは以下の通りです。

• 導入: Gradleに kotlin-serialization プラグインと kotlinx-serialization-json 依存関係を追加します。
• シリアライズ可能クラス: @Serializable アノテーションをデータクラスなどに付与することで、シリアライズ/デシリアライズの対象とします。組み込み型、コレクション、入れ子構造、Nullableプロパティ、デフォルト値などをサポートします。
• 変換: Json オブジェクトの encodeToString() メソッドでKotlinオブジェクトをJSONに、decodeFromString() メソッドでJSONをKotlinオブジェクトに変換します。
• カスタマイズ: Json { ... } ブロックで prettyPrint, ignoreUnknownKeys, isLenient, encodeDefaults, explicitNulls などのオプションを設定し、変換の挙動を調整できます。
• アノテーション: @SerialName でJSONキー名とプロパティ名をマッピングし、@Transient でプロパティを変換対象から除外できます。
• エラーハンドリング: JSON形式の不正、必須フィールドの欠落、未知のキー、型不一致などにより SerializationException が発生する可能性があるため、try-catch によるハンドリングや、適切な設定オプションの活用が必要です。
• 利点: Kotlinとの高い親和性、コンパイル時の安全性、マルチプラットフォーム対応、パフォーマンス、柔軟なカスタマイズ性などが挙げられます。

Kotlin Serializationは、KotlinプロジェクトにおけるJSON変換のベストプラクティスの一つと言えます。コンパイル時の安全性とKotlinネイティブな設計は、開発効率とアプリケーションの堅牢性を向上させます。

この記事で紹介した内容は、Kotlin Serializationを使ったJSON変換の「基本」です。ライブラリには、カスタムシリアライザー、ポリモーフィックシリアライズ（継承・多態性の扱い）、ストリームベースの変換など、さらに高度な機能も多数用意されています。これらの機能は、より複雑な要件に対応する必要がある場合に役立ちます。

まずはこの記事で解説した基本をしっかりと理解し、日々の開発で活用してみてください。JSONデータの扱いは、現代のアプリケーション開発において避けて通れない課題であり、Kotlin Serializationはその課題を効率的かつ安全に解決するための強力なツールとなるでしょう。

Happy coding!