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

Библиотеки

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

• Свойства: kotlinx-serialization-properties

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

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

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

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

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

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

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

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

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

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

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

   dependencies {
       implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.4.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.