Kotlin serialization: как настроить JSON на простом примере

Kotlin serialization — это официальный набор инструментов для преобразования Kotlin-объектов в JSON и обратно. Самый частый сценарий: у вас есть data class, вы добавляете @Serializable, а затем используете Json.encodeToString и Json.decodeFromString

Пример:

import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json

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

fun main() {
    val user = User(1, "Dinar")
    val json = Json.encodeToString(user)

    println(json)
}

Вывод:

{"id":1,"name":"Dinar"}

Что подключить в Gradle

Нужны две вещи: compiler plugin и runtime-библиотека

plugins {
    kotlin("jvm") version "2.3.21"
    kotlin("plugin.serialization") version "2.3.21"
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.10.0")
}

Версии подбирайте под текущий Kotlin-проект. Важно, чтобы serialization plugin соответствовал версии Kotlin. Если у вас в проекте уже стоит другая версия Kotlin, не копируйте числа вслепую, а выровняйте plugin под свою сборку

Как прочитать JSON обратно

import kotlinx.serialization.Serializable
import kotlinx.serialization.decodeFromString
import kotlinx.serialization.json.Json

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

fun main() {
    val json = """{"id":1,"name":"Dinar"}"""
    val user = Json.decodeFromString<User>(json)

    println(user.name)
}

Вывод:

Dinar

Если в JSON есть лишние поля

API часто возвращают больше данных, чем нужно приложению. Чтобы не падать на неизвестных полях, настройте Json:

val jsonParser = Json {
    ignoreUnknownKeys = true
}

После этого можно использовать:

val user = jsonParser.decodeFromString<User>(json)

Если имена полей отличаются

Иногда сервер возвращает user_name, а в Kotlin хочется поле userName. Для этого используют @SerialName

@Serializable
data class User(
    val id: Int,
    @SerialName("user_name")
    val userName: String
)

Так модель остается читаемой в Kotlin-коде, но корректно связывается с JSON

Как проверить

Создайте маленький data class, превратите его в JSON, затем прочитайте обратно. Если объект после чтения содержит те же значения, базовая настройка работает

Для удобной отладки можно включить красивый вывод:

val prettyJson = Json {
    prettyPrint = true
}

Так JSON будет занимать больше строк, зато его проще читать глазами в логах и учебных примерах. В production-ответах API обычно оставляют компактный JSON без лишних пробелов

Частые ошибки

Забыть @Serializable

Без аннотации библиотека не знает, как сериализовать ваш класс

Подключить зависимость без плагина

Одной runtime-библиотеки недостаточно. Для обычного проекта нужен serialization plugin

Не учитывать nullable-поля

Если поле может отсутствовать или быть null, отражайте это в модели:

val email: String? = null

Путать JSON-библиотеки

Не смешивайте в одном примере Gson, Jackson и kotlinx.serialization без необходимости. У каждой библиотеки свои аннотации и правила

Что почитать дальше по Kotlin

Если нужен общий маршрут по теме, откройте рубрику Kotlin. Для соседних задач пригодятся эти разборы:

• Coroutines в Kotlin: первый async-пример
• Inline в Kotlin: что это и когда использовать
• Kotlin Android: первый экран без перегруза
• Kotlin и Java: в чем разница для новичка