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

Библиотеки

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 и многоплатформенных проектах.

Обратите внимание, что библиотеки 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.6.20"
       kotlin("plugin.serialization") version "1.6.20"
   }
   

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

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

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

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

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