Kotlin Academy · Урок

Настройка kotlinx.serialization

Добавьте плагин

«Настройка kotlinx.serialization» — бесплатный урок Kotlin Academy на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Kotlin Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Kotlin Academy содержит 4 уроков всего.

Что такое kotlinx.serialization?

kotlinx.serialization — это официальная библиотека Kotlin для преобразования объектов в форматы вроде JSON и обратно.

Написана на Kotlin и готова к работе на разных платформах
Генерация кода во время компиляции без отражения
Поддерживается JetBrains

Она работает вместе с плагином компилятора и библиотекой времени выполнения.

Зачем нужен плагин компилятора?

В отличие от библиотек на основе отражения, kotlinx.serialization создаёт сериализаторы во время компиляции.

Работает быстрее, поскольку не требует затрат на отражение во время выполнения
Работает на Kotlin/Native и JS, где отражение ограничено
Безопасна с точки зрения типов и проверяется компилятором

Именно поэтому необходимо подключить плагин kotlin-serialization, а не только добавить зависимость.

Подключение плагина (Kotlin DSL)

В build.gradle.kts подключите плагин сериализации с той же версией, что и у плагина Kotlin.

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

Добавление зависимости времени выполнения

Плагин генерирует код, но Вам также понадобится библиотека времени выполнения JSON.

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

Важность согласования версий

Версия plugin.serialization должна совпадать с версией компилятора Kotlin. У библиотеки времени выполнения своя независимая версия.

Версия плагина = версия Kotlin (например, 2.0.0)
Версия библиотеки времени выполнения отдельная (например, 1.7.1)

Несовпадение версий плагина и Kotlin приводит к непонятным ошибкам сборки.

Другие форматы

JSON используется чаще всего, но kotlinx.serialization поддерживает и другие форматы с помощью дополнительных артефактов:

kotlinx-serialization-json — JSON
kotlinx-serialization-cbor — двоичный CBOR
kotlinx-serialization-protobuf — буферы протокола

Добавляйте только те артефакты форматов, которые Вам нужны.

Эквивалент для DSL Groovy

Если в Вашем проекте вместо DSL Kotlin используется Groovy build.gradle, настройка выглядит так.

// build.gradle (Groovy)
plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.0.0'
    id 'org.jetbrains.kotlin.plugin.serialization' version '2.0.0'
}

dependencies {
    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1'
}

Точка входа Json

После настройки используйте объект Json из kotlinx.serialization.json как основную точку входа для кодирования и декодирования.

import kotlinx.serialization.json.Json

val format = Json
// format.encodeToString(...) / format.decodeFromString(...)

Минимальный рабочий фрагмент

Ниже приведён самый короткий пример от начала до конца после настройки плагина и библиотеки времени выполнения.

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

@Serializable
data class City(val name: String, val population: Int)

fun main() {
    val city = City("Istanbul", 15000000)
    val json = Json.encodeToString(city)
    println(json)
}

Настройка мультиплатформенного проекта

В мультиплатформенном проекте Kotlin добавьте библиотеку времени выполнения в commonMain, чтобы все целевые платформы могли её использовать.

sourceSets {
    val commonMain by getting {
        dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
        }
    }
}

Распространённые ошибки настройки

Обратите внимание на следующие частые проблемы:

Забытый плагин — появляется сообщение Serializer has not been found
Версия плагина не совпадает с версией Kotlin
Добавлена библиотека времени выполнения, но не плагин, или наоборот
Отсутствует импорт encodeToString

Быстрая проверка

Почему для kotlinx.serialization требуется плагин компилятора Gradle?

Итоги

Вы настроили kotlinx.serialization следующим образом:

Подключили плагин kotlin("plugin.serialization"), соответствующий версии Kotlin
Добавили зависимость времени выполнения kotlinx-serialization-json
Использовали объект Json как точку входа

Далее Вы добавите аннотации к классам моделей с помощью @Serializable.

Часто задаваемые вопросы

Урок «Настройка kotlinx.serialization» бесплатный?

Да — полный текст урока «Настройка kotlinx.serialization» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Kotlin Academy, подпишись на CoddyKit PRO. Курс Kotlin Academy содержит 4 уроков всего.

Чему я научусь в уроке «Настройка kotlinx.serialization»?

Добавьте плагин Ты практикуешь Kotlin Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Kotlin Academy?

Предыдущий опыт не требуется. Kotlin Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Настройка kotlinx.serialization»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Kotlin Academy?

Да. Каждый урок Kotlin Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к Kotlin Academy