Kotlin Academy · Урок

Пользовательские сериализаторы

Обрабатывайте специальные типы

Урок 4 из 413 шагов

«Пользовательские сериализаторы» — бесплатный урок Kotlin Academy на CoddyKit. Это урок 4 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Kotlin Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Kotlin Academy содержит 4 уроков всего.

Зачем нужны пользовательские сериализаторы?

Для некоторых типов нет встроенного сериализатора: это java.util.Date, LocalDate, UUID и типы из сторонних библиотек.

Пользовательский сериализатор определяет, как такой тип преобразуется в сериализуемое представление и обратно.

Интерфейс KSerializer

Пользовательский сериализатор реализует KSerializer<T> с тремя членами: descriptor, serialize и deserialize.

import kotlinx.serialization.KSerializer
import kotlinx.serialization.descriptors.SerialDescriptor
import kotlinx.serialization.encoding.Decoder
import kotlinx.serialization.encoding.Encoder

Сериализатор для LocalDate

Преобразуйте LocalDate в строку ISO и обратно. Дескриптор объявляет этот тип как примитивную строку.

import java.time.LocalDate
import kotlinx.serialization.KSerializer
import kotlinx.serialization.descriptors.PrimitiveKind
import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor
import kotlinx.serialization.descriptors.SerialDescriptor
import kotlinx.serialization.encoding.Decoder
import kotlinx.serialization.encoding.Encoder

object LocalDateSerializer : KSerializer<LocalDate> {
    override val descriptor: SerialDescriptor =
        PrimitiveSerialDescriptor("LocalDate", PrimitiveKind.STRING)
    override fun serialize(encoder: Encoder, value: LocalDate) =
        encoder.encodeString(value.toString())
    override fun deserialize(decoder: Decoder): LocalDate =
        LocalDate.parse(decoder.decodeString())
}

Использование @Serializable(with = ...)

Примените сериализатор к определённому свойству с помощью @Serializable(with = ...).

import java.time.LocalDate
import kotlinx.serialization.Serializable

@Serializable
data class Event(
    val name: String,
    @Serializable(with = LocalDateSerializer::class)
    val date: LocalDate
)

@UseSerializers на уровне файла

Чтобы не добавлять аннотацию к каждому свойству, объявите сериализаторы один раз для всего файла с помощью @file:UseSerializers.

@file:UseSerializers(LocalDateSerializer::class)

import kotlinx.serialization.UseSerializers
import java.time.LocalDate
import kotlinx.serialization.Serializable

@Serializable
data class Event(val name: String, val date: LocalDate)

Контекстная сериализация

Зарегистрируйте сериализаторы глобально в модуле Json { } и пометьте свойства аннотацией @Contextual. Сериализатор определяется во время выполнения на основе модуля.

import kotlinx.serialization.Contextual
import kotlinx.serialization.Serializable
import java.time.LocalDate

@Serializable
data class Event(val name: String, @Contextual val date: LocalDate)

Регистрация SerializersModule

Создайте модуль, связывающий тип с его сериализатором, и передайте его объекту Json.

import kotlinx.serialization.json.Json
import kotlinx.serialization.modules.SerializersModule
import java.time.LocalDate

val module = SerializersModule {
    contextual(LocalDate::class, LocalDateSerializer)
}
val json = Json { serializersModule = module }

Составные сериализаторы

Для типов с несколькими полями используйте encodeStructure / decodeStructure со структурированным дескриптором вместо примитивного.

import kotlinx.serialization.descriptors.buildClassSerialDescriptor
import kotlinx.serialization.descriptors.element

val descriptor = buildClassSerialDescriptor("Color") {
    element<Int>("r")
    element<Int>("g")
    element<Int>("b")
}

Шаблон суррогата

Более простой вариант — сериализовать закрытый суррогатный класс данных, который уже поддерживается компилятором, а затем преобразовать его в Ваш реальный тип и обратно. Это требует меньше шаблонного кода, чем ручное кодирование и декодирование.

import kotlinx.serialization.Serializable

@Serializable
private data class ColorSurrogate(val r: Int, val g: Int, val b: Int)

Выбор подхода

Выберите самый простой подход, который подходит для Вашей задачи:

@Serializable(with=) — одно свойство
@UseSerializers — весь файл
@Contextual + модуль — всё приложение, определение во время выполнения
Суррогат — составные типы с минимальным количеством кода

Примитивный и структурированный дескрипторы

Дескриптор должен соответствовать способу кодирования:

Одно значение (строка или целое число) → PrimitiveSerialDescriptor
Несколько полей → buildClassSerialDescriptor

Несоответствие приводит к ошибкам сериализации во время выполнения.

Быстрая проверка

Вы хотите сериализовать один LocalDate как одну строку ISO. Какой дескриптор следует выбрать?

Ответь в интерактивном уроке

Итоги

Пользовательские сериализаторы обрабатывают типы, о которых плагин ничего не знает:

Реализуйте KSerializer<T> с дескриптором, сериализацией и десериализацией
Применяйте их через @Serializable(with=), @UseSerializers или @Contextual с модулем
Согласуйте вид дескриптора со способом кодирования

На этом курс по сериализации завершён.

Можно начать бесплатно

Изучай Kotlin с ИИ-репетитором — бесплатно

Пиши и запускай код прямо в браузере, получай мгновенную помощь от ИИ-репетитора 24/7 и продолжи учиться на сайте или в приложении.

Курсы: 51
Уроки: 203

Начать учиться бесплатно Посмотреть полный курс

Часто задаваемые вопросы

Урок «Пользовательские сериализаторы» бесплатный?

Да — полный текст урока «Пользовательские сериализаторы» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Kotlin Academy, подпишись на CoddyKit PRO. Курс Kotlin Academy содержит 4 уроков всего.

Чему я научусь в уроке «Пользовательские сериализаторы»?

Обрабатывайте специальные типы Ты практикуешь Kotlin Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Kotlin Academy?

Предыдущий опыт не требуется. Kotlin Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 4 из 4.

Сколько времени занимает урок «Пользовательские сериализаторы»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Kotlin Academy?

Да. Каждый урок Kotlin Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к Kotlin Academy