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

Библиотеки

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

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

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

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

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

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

Форматы

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

• JSON: kotlinx-serialization-json

• Protocol buffers: kotlinx-serialization-protobuf

• CBOR: kotlinx-serialization-cbor

• Properties: kotlinx-serialization-properties

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

Обратите внимание, что все библиотеки, кроме сериализации JSON (kotlinx-serialization-json), являются Экспериментальными, что означает, что их 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.9.0"
       kotlin("plugin.serialization") version "1.9.0"
   }
   

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

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

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

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

Теперь вы готовы использовать 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.