JSONマッピングのためのKotlinシリアライゼーションアノテーション

kotlinx.serializationアノテーション

Kotlinの公式シリアライゼーションライブラリは、data classがJSONにどのようにエンコード・デコードされるかを制御するためにアノテーションを使用します。これらのアノテーションを理解することが正確なJSONマッピングに不可欠です。

コアアノテーション

@Serializable
data class User(
    @SerialName("user_id")
    val userId: Int,

    val name: String,

    @Transient
    val cachedHash: Int = 0,

    @EncodeDefault
    val role: String = "viewer",

    @Required
    val email: String
)

アノテーションリファレンス

アノテーション	目的
@Serializable	クラスをシリアライゼーション対象にマーク；シリアライザーを生成
@SerialName("key")	プロパティを異なるJSONキーにマッピング
@Transient	プロパティをシリアライゼーションから完全に除外
@EncodeDefault	デフォルト値と一致する場合でも出力に含める
@Required	デシリアライゼーション時にフィールドを必須にする（デフォルトなし）

キーマッピングの@SerialName

ほとんどのJSON APIはsnake_caseを使用し、KotlinはcamelCaseを使用します：

@Serializable
data class Event(
    @SerialName("event_id") val eventId: String,
    @SerialName("created_at") val createdAt: String,
    @SerialName("is_public") val isPublic: Boolean
)

内部フィールドの@Transient

@Serializable
data class CachedUser(
    val id: Int,
    val name: String,
    @Transient
    val fetchedAt: Long = System.currentTimeMillis()
)

fetchedAtフィールドはKotlinオブジェクトに存在しますが、JSON出力に表示されず、JSON入力から読み取られることもありません。デフォルト値が必須です。

@EncodeDefaultモード

@Serializable
data class Settings(
    @EncodeDefault(EncodeDefault.Mode.ALWAYS)
    val theme: String = "light",

    @EncodeDefault(EncodeDefault.Mode.NEVER)
    val internal: String = "default"
)

• ALWAYS -- デフォルトと同じ場合でもJSONに含める
• NEVER -- デフォルトと同じ場合はJSONから省略（これがグローバルデフォルト動作）

アノテーションの組み合わせ

@Serializable
data class ApiConfig(
    @SerialName("base_url")
    @Required
    val baseUrl: String,

    @SerialName("retry_count")
    @EncodeDefault
    val retryCount: Int = 3
)

これらのアノテーションにより、JSONソースを変更せずにJSON-to-Kotlinマッピングを完全に制御できます。