Сериализация встроенных типов

Числа

Можно сериализовать все числовые типы Kotlin, включая целые числа и числа с плавающей точкой, используя их естественное представление в JSON:

import kotlinx.serialization.*
import kotlinx.serialization.json.*
import kotlin.math.PI

//sampleStart
@Serializable
class Data(
    val answer: Int,
    val pi: Double
)                     

fun main() {
    val data = Data(42, PI)
    println(Json.encodeToString(data))
    // {"answer":42,"pi":3.141592653589793}
}
//sampleEnd

Беззнаковые числа

Сериализация Kotlin поддерживает беззнаковые целочисленные типы Kotlin, такие как UByte и UInt. В JSON эти значения сериализуются как обычные числа JSON и сохраняют весь диапазон беззнаковых значений:

import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
@Serializable
class Counter(val counted: UByte, val description: String)

fun main() {
    val counted = 239.toUByte()
    println(Json.encodeToString(Counter(counted, "tries")))
    // {"counted":239,"description":"tries"}
}
//sampleEnd

Числа Long в виде строк

В JSON можно представлять числа Long в виде строк. Это полезно в средах JavaScript, где тип Number в JavaScript не может точно представить все значения Long в Kotlin, что может привести к потере точности.

Используйте LongAsStringSerializer с аннотацией @Serializable, чтобы кодировать значения Long в виде строк в JSON:

import kotlinx.serialization.*
import kotlinx.serialization.builtins.*
import kotlinx.serialization.json.*

//sampleStart
@Serializable
class Data(
    @Serializable(LongAsStringSerializer::class)
    val signature: Long
)

fun main() {
    val data = Data(0x1CAFE2FEED0BABE0)
    println(Json.encodeToString(data))
    // {"signature":"2067120338512882656"}
}
//sampleEnd

Классы-перечисления

Все классы enum сериализуемы по умолчанию без аннотации @Serializable. При сериализации в JSON значение enum кодируется в виде строки:

import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
// The @Serializable annotation isn't required for enum classes
enum class Status { SUPPORTED }

@Serializable
class Project(val name: String, val status: Status) 

fun main() {
    val data = Project("kotlinx.serialization", Status.SUPPORTED)
    println(Json.encodeToString(data))
    // {"name":"kotlinx.serialization","status":"SUPPORTED"}
}
//sampleEnd

import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
// Requires the @Serializable annotation because of @SerialName
@Serializable
enum class Status { @SerialName("maintained") SUPPORTED }

@Serializable
class Project(val name: String, val status: Status) 

fun main() {
    val data = Project("kotlinx.serialization", Status.SUPPORTED)
    println(Json.encodeToString(data))
    // {"name":"kotlinx.serialization","status":"maintained"}
}
//sampleEnd

Pair и Triple

Можно сериализовать классы Pair и Triple из стандартной библиотеки Kotlin:

import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
@Serializable
class Project(val name: String)

fun main() {
    val pair = 1 to Project("kotlinx.serialization")
    println(Json.encodeToString(pair))
    // {"first":1,"second":{"name":"kotlinx.serialization"}}
}
//sampleEnd

Коллекции

Сериализация Kotlin поддерживает типы коллекций, включая как неизменяемые, так и изменяемые варианты List, Set и Map. Также поддерживаются конкретные реализации, такие как ArrayList и LinkedHashSet, а также обобщённые и примитивные типы массивов. Представление этих коллекций зависит от формата сериализации.

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

Для десериализации JSON Kotlin использует объявленный тип. При десериализации тип результирующего объекта определяется статическим типом, указанным в исходном коде. Это может быть тип свойства или параметр типа функции декодирования.

import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
@Serializable
class Project(val name: String)

fun main() {
    val list = listOf(
        Project("kotlinx.serialization"),
        Project("kotlinx.coroutines")    
    )
    println(Json.encodeToString(list))
    // [{"name":"kotlinx.serialization"},{"name":"kotlinx.coroutines"}]
}
//sampleEnd

import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
@Serializable
class Project(val name: String)

fun main() {
    val set = setOf(
        Project("kotlinx.serialization"),
        Project("kotlinx.coroutines")    
    )
    println(Json.encodeToString(set))
    // [{"name":"kotlinx.serialization"},{"name":"kotlinx.coroutines"}]
}
//sampleEnd

import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
@Serializable
class Project(val name: String)

fun main() {
    // Creates a map with Int keys
    val map = mapOf(
        1 to Project("kotlinx.serialization"),
        2 to Project("kotlinx.coroutines")    
    )
    println(Json.encodeToString(map))
    // {"1":{"name":"kotlinx.serialization"},"2":{"name":"kotlinx.coroutines"}}
}
//sampleEnd

import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
@Serializable
data class Data(
    val a: List<Int>,
    val b: Set<Int>
)

fun main() {
    val data = Json.decodeFromString<Data>("""
        {
            "a": [42, 42],
            "b": [42, 42]
        }
    """)
    // Duplicates are removed from data.b because the Set type enforces unique elements
    println(data)
    // Data(a=[42, 42], b=[42])
}
//sampleEnd

Unit и объекты-одиночки

Тип Unit в Kotlin и другие объекты-одиночки сериализуемы. Объект-одиночка — это класс с единственным экземпляром, состояние которого определяется самим объектом, а не внешними свойствами. В JSON объекты-одиночки сериализуются как пустые структуры:

import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
@Serializable
object SerializationVersion {
    val libraryVersion: String = "1.0.0"
}

fun main() {
    println(Json.encodeToString(SerializationVersion))
    // {}
    println(Json.encodeToString(Unit))
    // {}
}
//sampleEnd

Duration и Instant

Тип Duration в Kotlin сериализуется в строку в формате ISO-8601-2:

import kotlinx.serialization.*
import kotlinx.serialization.json.*
import kotlin.time.*

//sampleStart
fun main() {
    val duration = 1000.toDuration(DurationUnit.SECONDS)
    println(Json.encodeToString(duration))
    // "PT16M40S"
}
//sampleEnd

Тип Instant в Kotlin также можно сериализовать в виде строки, представляющей момент времени в формате ISO-8601-1:

import kotlinx.serialization.*
import kotlinx.serialization.json.*
import kotlin.time.*

//sampleStart
fun main() {
    val instant = Instant.fromEpochMilliseconds(1607505416124)
    println(Json.encodeToString(instant))
    // "2020-12-09T09:16:56.124Z"
}
//sampleEnd

Nothing

Тип Nothing сериализуем по умолчанию. У него нет экземпляров, поэтому при кодировании или декодировании возникает исключение. Используйте Nothing, когда тип необходим синтаксически, но не участвует в сериализации, например в полиморфной иерархии с обобщённым базовым типом:

import kotlinx.serialization.*
import kotlinx.serialization.builtins.*
import kotlinx.serialization.json.*

//sampleStart
@Serializable
sealed class ParametrizedParent<out R> {
    @Serializable
    data class ChildWithoutParameter(val value: Int) : ParametrizedParent<Nothing>()
}

fun main() {
    println(Json.encodeToString(ParametrizedParent.ChildWithoutParameter(42)))
    // {"value":42}
}
//sampleEnd