Сериализация

Библиотеки

kotlinx.serialization предоставляет наборы библиотек для всех поддерживаемых платформ — JVM, JavaScript, Native — и для различных форматов сериализации — JSON, CBOR, протобуферы и другие. Полный список поддерживаемых форматов сериализации можно найти ниже.

Все библиотеки сериализации Kotlin относятся к группе org.jetbrains.kotlinx:. Их имена начинаются с kotlinx-serialization- и имеют суффиксы, отражающие формат сериализации. Примеры:

• org.jetbrains.kotlinx:kotlinx-serialization-json предоставляет сериализацию JSON для проектов Kotlin.

• org.jetbrains.kotlinx:kotlinx-serialization-cbor предоставляет сериализацию CBOR.

Платформенно-специфические артефакты обрабатываются автоматически; вам не нужно добавлять их вручную. Используйте одни и те же зависимости в проектах JVM, JS, Native и multiplatform.

Обратите внимание, что библиотеки kotlinx.serialization используют свою собственную структуру версионирования, которая не соответствует версионированию Kotlin. Проверьте выпуски на GitHub, чтобы найти последние версии.

Форматы

kotlinx.serialization включает библиотеки для различных форматов сериализации:

• JSON: kotlinx-serialization-json

• Протобуферы: kotlinx-serialization-protobuf

• CBOR: kotlinx-serialization-cbor

• Properties: kotlinx-serialization-properties

• HOCON: kotlinx-serialization-hocon (только на JVM)

Обратите внимание, что все библиотеки, кроме сериализации JSON (kotlinx-serialization-core), являются экспериментальными, что означает, что их API может быть изменён без предварительного уведомления.

Также существуют библиотеки, поддерживаемые сообществом, которые поддерживают больше форматов сериализации, такие как YAML или Apache Avro. Для получения подробной информации о доступных форматах сериализации см. kotlinx.serialization документацию.

Пример: сериализация JSON

Давайте посмотрим, как сериализовать объекты Kotlin в JSON.

Прежде чем начать, вам нужно настроить скрипт сборки, чтобы использовать инструменты сериализации Kotlin в вашем проекте:

1. Примените плагин Gradle для сериализации Kotlin org.jetbrains.kotlin.plugin.serialization (или kotlin("plugin.serialization") в Kotlin Gradle DSL).

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

   plugins {
       id 'org.jetbrains.kotlin.jvm' version '1.7.20'
       id 'org.jetbrains.kotlin.plugin.serialization' version '1.7.20'  
   }
   

2. Добавьте зависимость библиотеки сериализации JSON:org.jetbrains.kotlinx:kotlinx-serialization-json:1.4.0

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

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

Теперь вы готовы использовать API сериализации в своём коде. API расположен в пакете kotlinx.serialization и его формат-специфических подпакетах, таких как kotlinx.serialization.json.

Сначала сделайте класс сериализуемым, добавив к нему аннотацию @Serializable.

import kotlinx.serialization.Serializable

@Serializable
data class Data(val a: Int, val b: String)

Теперь вы можете сериализовать экземпляр этого класса, вызвав Json.encodeToString().

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

@Serializable
data class Data(val a: Int, val b: String)

fun main() {
   val json = Json.encodeToString(Data(42, "str"))
}

В результате вы получите строку, содержащую состояние этого объекта в формате JSON: {"a": 42, "b": "str"}

Вы также можете сериализовать коллекции объектов, такие как списки, в одном вызове.

val dataList = listOf(Data(42, "str"), Data(12, "test"))
val jsonList = Json.encodeToString(dataList)

Для десериализации объекта из JSON используйте функцию decodeFromString():

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

@Serializable
data class Data(val a: Int, val b: String)

fun main() {
   val obj = Json.decodeFromString<Data>("""{"a":42, "b": "str"}""")
}

Дополнительную информацию о сериализации в Kotlin см. в руководстве по сериализации Kotlin.