Kotlin Academy · Lekcja

Niestandardowe serializery

Obsługuj specjalne typy

Niestandardowe serializery to bezpłatna lekcja Kotlin Academy na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Kotlin Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Kotlin Academy zawiera 4 lekcji w sumie.

Dlaczego potrzebne są własne serializatory?

Niektóre typy nie mają wbudowanego serializatora: java.util.Date, LocalDate, UUID lub typy z bibliotek innych firm.

Własny serializator określa sposób mapowania takiego typu na postać serializowaną i z powrotem.

Interfejs KSerializer

Własny serializator implementuje KSerializer<T> z trzema elementami: descriptor, serialize i deserialize.

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

Serializator dla LocalDate

Typ LocalDate można mapować na ciąg ISO i z powrotem. Deskryptor określa go jako prymitywny ciąg znaków.

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())
}

Używanie @Serializable(with = ...)

Serializator można zastosować do konkretnej właściwości za pomocą @Serializable(with = ...).

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

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

Adnotacja @UseSerializers na poziomie pliku

Aby uniknąć oznaczania każdej właściwości, należy zadeklarować serializatory raz dla całego pliku za pomocą @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)

Serializacja kontekstowa

Serializatory można rejestrować globalnie w konfiguracji Json { } i oznaczać właściwości adnotacją @Contextual. Serializator jest wyszukiwany w czasie działania w skonfigurowanym module.

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

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

Rejestrowanie SerializersModule

Należy utworzyć moduł wiążący typ z jego serializatorem i przekazać go do 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 }

Serializatory złożone

W przypadku typów z wieloma polami należy użyć encodeStructure / decodeStructure ze strukturalnym deskryptorem zamiast deskryptora prymitywnego.

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

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

Wzorzec klasy zastępczej

Prostsza alternatywa polega na serializowaniu prywatnej klasy danych zastępczej, którą kompilator już obsługuje, a następnie mapowaniu jej na rzeczywisty typ i z powrotem. Wymaga to mniej kodu pomocniczego niż ręczne kodowanie i dekodowanie.

import kotlinx.serialization.Serializable

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

Wybór podejścia

Należy wybrać najprostsze podejście odpowiednie do danego przypadku:

@Serializable(with=) — jedna właściwość
@UseSerializers — cały plik
@Contextual + moduł — w całej aplikacji, rozwiązywane w czasie działania
Klasa zastępcza — typy złożone przy minimalnej ilości kodu

Deskryptor prymitywny a strukturalny

Deskryptor musi odpowiadać sposobowi kodowania:

Pojedyncza wartość (string/int) → PrimitiveSerialDescriptor
Wiele pól → buildClassSerialDescriptor

Niezgodność powoduje błędy serializacji w czasie działania.

Szybkie sprawdzenie

Potrzebna jest serializacja pojedynczego elementu LocalDate jako jednego ciągu ISO. Który deskryptor jest odpowiedni?

Podsumowanie

Własne serializatory obsługują typy, których wtyczka nie zna:

Implementacja KSerializer<T> z elementami descriptor + serialize + deserialize
Zastosowanie za pomocą @Serializable(with=), @UseSerializers lub @Contextual + modułu
Dopasowanie rodzaju deskryptora do sposobu kodowania

To kończy kurs dotyczący serializacji.

Często zadawane pytania

Czy lekcja „Niestandardowe serializery” jest bezpłatna?

Tak — pełny tekst „Niestandardowe serializery” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Kotlin Academy, przejdź na CoddyKit PRO. Kurs Kotlin Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Niestandardowe serializery”?

Obsługuj specjalne typy Ćwiczysz Kotlin Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Kotlin Academy?

Nie wymagamy żadnego doświadczenia. Kotlin Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.

Ile czasu zajmuje lekcja „Niestandardowe serializery”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Kotlin Academy?

Tak. Każda lekcja Kotlin Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do Kotlin Academy