kotlinx.serialization: τι είναι, σχολιασμοί και σειριοποίηση σε JSON

Τι είναι το kotlinx.serialization

kotlinx.serialization — είναι μια ενσωματωμένη βιβλιοθήκη σειριοποίησης για Kotlin, που αναπτύχθηκε από τη JetBrains ως μέρος του επίσημου οικοσυστήματος Kotlin. Η κύρια διαφορά της από λύσεις τρίτων (Gson, Moshi, Jackson) είναι ότι δεν χρησιμοποιεί ανάκλαση κατά το χρόνο εκτέλεσης. Αντί αυτού, ο κώδικας σειριοποιητή δημιουργείται στο στάδιο μεταγλώττισης με χρήση του Kotlin Symbol Processing (KSP) ή του Kotlin Compiler Plugin. Αυτό παρέχει αύξηση απόδοσης έως 3-5 φορές σε σύγκριση με το Gson και εγγυάται ασφάλεια τύπων.

Η βιβλιοθήκη υποστηρίζει επίσημα τέσσερις μορφές: JSON (μέσω της ενότητας kotlinx-serialization-json), ProtoBuf (kotlinx-serialization-protobuf), CBOR (kotlinx-serialization-cbor) και HOCON (kotlinx-serialization-hocon). Οι μορφές προστίθενται ως ξεχωριστές εξαρτήσεις στο build.gradle.kts, επιτρέποντας να μην μεταφέρονται περιττές βιβλιοθήκες στο έργο. Για κάθε μορφή υπάρχει ένα ξεχωριστό σύνολο παραμέτρων ρύθμισης.

Πολυπλατφορμικότητα — το βασικό χαρακτηριστικό της βιβλιοθήκης. Η ίδια κλάση με @Serializable λειτουργεί σε όλες τις πλατφόρμες-στόχους: JVM (Android, Backend), Native (iOS), JS (Web, React) και Wasm (WebAssembly). Ο προγραμματιστής δεν χρειάζεται να γράψει διαφορετικές υλοποιήσεις σειριοποίησης για κάθε πλατφόρμα — ο κώδικας παραμένει ενιαίος. Αυτό είναι ιδιαίτερα πολύτιμο σε έργα Kotlin Multiplatform Mobile (KMM), όπου ο κοινός κώδικας μοιράζεται μεταξύ Android και iOS.

Πώς λειτουργεί η δημιουργία κώδικα κατά τη μεταγλώττιση

Δημιουργία κώδικα στο kotlinx.serialization πραγματοποιείται σε τρία στάδια. Στο πρώτο στάδιο, ο μεταγλωττιστής Kotlin ανιχνεύει τον σχολιασμό @Serializable σε μια κλάση και τον μεταβιβάζει στο πρόσθετο Kotlin Symbol Processing (KSP). Στο δεύτερο στάδιο, το KSP δημιουργεί ένα αντικείμενο σειριοποιητή που υλοποιεί τη διεπαφή KSerializer. Στο τρίτο στάδιο, ο δημιουργημένος κώδικας μεταγλωττίζεται μαζί με τον πηγαίο κώδικα του έργου. Ως αποτέλεσμα, κανένα από αυτά τα στάδια δεν εκτελείται κατά την εκτέλεση της εφαρμογής.

Ο δημιουργημένος σειριοποιητής λειτουργεί απευθείας με τα πεδία της κλάσης μέσω των getter και setter τους, χωρίς ανάκλαση. Αυτό σημαίνει ότι πεδία με τον τροποποιητή private επίσης σειριοποιούνται, εάν έχουν επισημανθεί με @Serializable. Η απόδοση αυτής της προσέγγισης είναι κοντά στη χειροκίνητη σειριοποίηση: για απλές κλάσεις (5-10 πεδία) ο χρόνος σειριοποίησης είναι 10-50 μικροδευτερόλεπτα, για σύνθετα γραφήματα αντικειμένων — έως 200 μικροδευτερόλεπτα ανά 1000 αντικείμενα.

Για τη σύνδεση της βιβλιοθήκης σε ένα έργο Android ή Kotlin/JVM, πρέπει να προστεθεί το πρόσθετο και οι εξαρτήσεις στο build.gradle.kts. Το πρόσθετο org.jetbrains.kotlin.plugin.serialization σε έκδοση που αντιστοιχεί στην έκδοση Kotlin ενεργοποιεί τη δημιουργία κώδικα. Η βιβλιοθήκη kotlinx-serialization-json προστίθεται στην ενότητα dependencies με έκδοση ανεξάρτητη από την έκδοση Kotlin.

// build.gradle.kts — σύνδεση kotlinx.serialization
plugins {
    val kotlinVersion = "2.1.0"
    kotlin("jvm") version kotlinVersion
    kotlin("plugin.serialization") version kotlinVersion
}

dependencies {
    // Κύρια ενότητα σειριοποίησης
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")

    // Πρόσθετες μορφές
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-protobuf:1.7.3")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-cbor:1.7.3")
}

Βασική χρήση: σειριοποίηση σε JSON

JSON — η πιο δημοφιλής μορφή στο kotlinx.serialization. Για τη σειριοποίηση ενός αντικειμένου, αρκεί να τοποθετήσετε τον σχολιασμό @Serializable σε ένα data class και να καλέσετε το Json.encodeToString(). Για αποσειριοποίηση — Json.decodeFromString() με καθορισμό τύπου. Η βιβλιοθήκη χειρίζεται αυτόματα πεδία null, λίστες, ένθετα αντικείμενα και απαριθμήσεις. Όλα τα πεδία της κλάσης είναι από προεπιλογή υποχρεωτικά, εκτός αν ορίζεται διαφορετικά.

Η ρύθμιση του JSON πραγματοποιείται μέσω του Json {} builder. Στον κατασκευαστή μπορούν να μεταβιβαστούν ignoreUnknownKeys = true για παράβλεψη άγνωστων πεδίων κατά την αποσειριοποίηση, prettyPrint = true για μορφοποιημένη έξοδο, coerceInputValues = true για μετατροπή εσφαλμένων τιμών σε προεπιλεγμένες. Επίσης διαθέσιμες είναι οι ρυθμίσεις encodeDefaults (σειριοποίηση πεδίων με προεπιλεγμένες τιμές) και classDiscriminator (όνομα πεδίου για πολυμορφική σειριοποίηση).

// Παράδειγμα σειριοποίησης και αποσειριοποίησης JSON
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonConfiguration

@Serializable
data class Project(
    val name: String,
    val stars: Int,
    val isActive: Boolean = true,
    val languages: List<String> = emptyList()
)

fun main() {
    val project = Project(
        name = "kotlinx.serialization",
        stars = 7200,
        languages = listOf("Kotlin", "Java")
    )

    // Σειριοποίηση σε JSON με prettyPrint
    val json = Json { prettyPrint = true }
    val jsonString = json.encodeToString(project)
    println(jsonString)
    /*
    {
        "name": "kotlinx.serialization",
        "stars": 7200,
        "isActive": true,
        "languages": ["Kotlin", "Java"]
    }
    */

    // Αποσειριοποίηση από JSON
    val decoded = json.decodeFromString<Project>(jsonString)
    println(decoded.name)  // kotlinx.serialization
}

Το παράδειγμα δείχνει τον βασικό κύκλο σειριοποίησης και αποσειριοποίησης. Το data class Project με τον σχολιασμό @Serializable αποκτά αυτόματα encodeToString και decodeFromString. Το πεδίο isActive έχει προεπιλεγμένη τιμή true — αν αυτό το πεδίο λείπει από το JSON, χρησιμοποιείται η προεπιλεγμένη τιμή. Αν έρθουν άγνωστα πεδία στο JSON χωρίς ignoreUnknownKeys = true, θα εκτιναχθεί εξαίρεση SerializationException.

Πολυμορφική σειριοποίηση sealed class

Sealed class — μία από τις πιο ισχυρές περιπτώσεις χρήσης του kotlinx.serialization. Η βιβλιοθήκη υποστηρίζει πολυμορφική σειριοποίηση για ιεραρχίες sealed class χωρίς πρόσθετη ρύθμιση: αρκεί να επισημάνετε το sealed class και όλους τους απογόνους του με @Serializable. Κατά τη σειριοποίηση προστίθεται το πεδίο „type” (ρυθμιζόμενο μέσω classDiscriminator), βάσει του οποίου κατά την αποσειριοποίηση προσδιορίζεται ο συγκεκριμένος τύπος.

// Πολυμορφική σειριοποίηση sealed class
@Serializable
sealed class Response

@Serializable
data class Success(val data: String) : Response()

@Serializable
data class Error(val code: Int, val message: String) : Response()

fun main() {
    val json = Json { classDiscriminator = "result_type" }

    val responses: List<Response> = listOf(
        Success(data = "Data loaded"),
        Error(code = 404, message = "Not found")
    )

    val jsonString = json.encodeToString(responses)
    println(jsonString)
    /*
    [
        {"result_type":"Success","data":"Data loaded"},
        {"result_type":"Error","code":404,"message":"Not found"}
    ]
    */

    val decoded = json.decodeFromString<List<Response>>(jsonString)
    when (val first = decoded[0]) {
        is Success -> println("Success: ${first.data}")
        is Error -> println("Error: ${first.code}")
    }
}

Η πολυμορφική σειριοποίηση sealed class είναι ιδιαίτερα χρήσιμη σε πελάτες API, όπου ο διακομιστής επιστρέφει διαφορετικούς τύπους απαντήσεων. Χωρίς kotlinx.serialization θα έπρεπε να γράψετε έναν χειροκίνητο αποσειριοποιητή με when βάσει του πεδίου διαχωρισμού. Με τη βιβλιοθήκη αυτό γίνεται με έναν σχολιασμό. Το classDiscriminator επιτρέπει την αλλαγή του ονόματος του πεδίου-δείκτη (προεπιλογή „type”) σε οποιαδήποτε τιμή αναμένει ο διακομιστής.

Σχολιασμοί kotlinx.serialization: πλήρης επισκόπηση

Η βιβλιοθήκη παρέχει ένα σύνολο σχολιασμών για λεπτομερή ρύθμιση της σειριοποίησης. Ο κύριος είναι @Serializable για την κλάση. Πρόσθετοι σχολιασμοί: @SerialName για τον καθορισμό του ονόματος πεδίου στο JSON (αν διαφέρει από το όνομα Kotlin), @Transient για εξαίρεση πεδίου από τη σειριοποίηση, @Required για πεδίο που πρέπει να υπάρχει στο JSON, @EncodeDefault για υποχρεωτική σειριοποίηση πεδίου με προεπιλεγμένη τιμή.

Ο σχολιασμός @SerialName είναι κρίσιμος όταν εργάζεστε με API όπου τα ονόματα πεδίων είναι σε snake_case και το στυλ Kotlin είναι camelCase. Για παράδειγμα, ο διακομιστής στέλνει “user_id” και στον κώδικα Kotlin χρησιμοποιείται userId. Το @SerialName(“user_id”) λύνει αυτό το πρόβλημα χωρίς πρόσθετους αντιστοιχιστές. Το @Transient είναι χρήσιμο για πεδία που δεν χρειάζεται να σταλούν στον διακομιστή — για παράδειγμα, προσωρινές υπολογισμένες τιμές ή προσωρινή μνήμη.

@Required ως εναλλακτική για πεδία nullable

Από προεπιλογή όλα τα πεδία στο kotlinx.serialization είναι υποχρεωτικά. Αν ένα πεδίο μπορεί να λείπει από το JSON, πρέπει να το κάνετε nullable (String?) ή να ορίσετε προεπιλεγμένη τιμή (val name: String = “”). Υπάρχουν όμως περιπτώσεις όπου το πεδίο δεν είναι nullable στην Kotlin αλλά μπορεί να λείπει από το JSON λόγω εκδόσεων του API. Σε αυτή την περίπτωση, το @Required εκτινάσσει SerializationException όταν το πεδίο απουσιάζει, ενώ η προεπιλεγμένη τιμή συμπληρώνει το default χωρίς σφάλμα.

Προσαρμοσμένοι σειριοποιητές: KSerializer και χειροκίνητη διαχείριση

KSerializer — διεπαφή που υλοποιούν όλοι οι σειριοποιητές στο kotlinx.serialization. Αν η τυπική δημιουργία κώδικα δεν είναι κατάλληλη (για παράδειγμα, για εργασία με Date, Bitmap ή συγκεκριμένη δυαδική μορφή), μπορείτε να γράψετε τον δικό σας σειριοποιητή. Για αυτό, πρέπει να υλοποιήσετε τις μεθόδους serialize() και deserialize(), καθώς και να παρέχετε έναν περιγραφέα — περιγραφή δομής για το σχήμα της μορφής.

Οι προσαρμοσμένοι σειριοποιητές συνδέονται με δύο τρόπους: μέσω του σχολιασμού @Serializable(with = MySerializer::class) για σύνδεση σε συγκεκριμένη κλάση ή καθολικά μέσω Json { serializersModule = ... } για σύνδεση σε όλες τις εμφανίσεις του τύπου. Ο δεύτερος τρόπος είναι προτιμότερος για ενσωματωμένους τύπους (Date, UUID) για να μην χρειάζεται να γράφετε σχολιασμό σε κάθε πεδίο.

// Προσαρμοσμένος σειριοποιητής για java.util.Date
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
import java.text.SimpleDateFormat
import java.util.Date
import java.util.Locale

object DateSerializer : KSerializer<Date> {
    private val dateFormat = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'", Locale.US)

    override val descriptor: SerialDescriptor =
        PrimitiveSerialDescriptor("Date", PrimitiveKind.STRING)

    override fun serialize(encoder: Encoder, value: Date) {
        encoder.encodeString(dateFormat.format(value))
    }

    override fun deserialize(decoder: Decoder): Date {
        return dateFormat.parse(decoder.decodeString())
    }
}

// Χρήση προσαρμοσμένου σειριοποιητή
@Serializable
data class Event(
    val title: String,
    @Serializable(with = DateSerializer::class)
    val date: Date
)

fun main() {
    val json = Json { prettyPrint = true }
    val event = Event("Κυκλοφορία", Date())
    println(json.encodeToString(event))
}

Στο παράδειγμα, ο DateSerializer μετατρέπει το java.util.Date σε συμβολοσειρά ISO 8601. Χωρίς προσαρμοσμένο σειριοποιητή, το kotlinx.serialization δεν μπορεί να εργαστεί με Date — είναι ένας τύπος που δεν ανήκει στην τυπική βιβλιοθήκη Kotlin. Το @Serializable(with = DateSerializer::class) σε ένα συγκεκριμένο πεδίο συνδέει τον σειριοποιητή μόνο για αυτό το πεδίο. Για καθολική καταχώρηση όλων των Date, χρησιμοποιήστε Json { serializersModule = SerializersModule { contextual(DateSerializer) } }.

Μορφές σειριοποίησης: JSON, ProtoBuf, CBOR, HOCON

kotlinx.serialization δεν περιορίζεται μόνο στο JSON. Η βιβλιοθήκη υποστηρίζει τέσσερις ενσωματωμένες μορφές, η καθεμία με τη δική της ενότητα και ρύθμιση. JSON (kotlinx-serialization-json) — καθολική, αναγνώσιμη από άνθρωπο, κατάλληλη για REST API. ProtoBuf (kotlinx-serialization-protobuf) — δυαδική, συμπαγής, με υποχρεωτικό σχήμα, για μικροϋπηρεσίες υψηλού φορτίου. CBOR (kotlinx-serialization-cbor) — δυαδικό αντίστοιχο του JSON, βολικό για IoT και κινητές συσκευές με περιορισμένη κίνηση. HOCON (kotlinx-serialization-hocon) — μορφή ρύθμισης, συμβατή με TypeSafe Config.

ProtoBuf απαιτεί ορισμό σχήματος σε αρχεία .proto, αλλά το kotlinx-serialization-protobuf δημιουργεί κλάσεις Kotlin απευθείας από @Serializable χωρίς .proto. Αυτό απλοποιεί την ανάπτυξη: αρκεί να σχολιάσετε ένα data class και να χρησιμοποιήσετε το ProtoBuf.encodeToByteArray(). Το CBOR είναι ιδιαίτερα σχετικό για το πλαίσιο Android όταν χρειάζεται να μεταδώσετε συμπαγή δυαδικά δεδομένα μέσω NFC ή BLE. Το μέγεθος μηνύματος CBOR είναι κατά μέσο όρο 20-30% μικρότερο από το JSON για το ίδιο σύνολο δεδομένων.

Επιλογή μορφής για το έργο

Για REST API σε κινητή εφαρμογή, το JSON είναι βέλτιστο — αποσφαλματώνεται χωρίς πρόσθετα εργαλεία, είναι αναγνώσιμο σε αρχεία καταγραφής και συμβατό με οποιοδήποτε backend. Αν η εφαρμογή μεταφέρει μεγάλους όγκους δεδομένων μεταξύ μικροϋπηρεσιών (εκατοντάδες megabyte) — το ProtoBuf θα δώσει αύξηση ταχύτητας έως 5 φορές χάρη στη δυαδική κωδικοποίηση. Για αποθήκευση ρυθμίσεων σε αρχεία, χρησιμοποιήστε HOCON ή JSON. Για συσκευές με αυστηρούς περιορισμούς κίνησης (αισθητήρες IoT) — CBOR.

Συνήθη λάθη κατά την εργασία με kotlinx.serialization

Πρώτο λάθος — παράβλεψη άγνωστων κλειδιών κατά την αποσειριοποίηση. Αν ο διακομιστής πρόσθεσε νέο πεδίο και έχετε ignoreUnknownKeys = false, η εφαρμογή θα καταρρεύσει με SerializationException. Από προεπιλογή αυτή η σημαία είναι απενεργοποιημένη. Λύση: ορίζετε πάντα Json { ignoreUnknownKeys = true } για κώδικα παραγωγής για να είστε ανθεκτικοί σε αλλαγές API.

Δεύτερο λάθος — σειριοποίηση internal ή private πεδίων σε data class. Σε Kotlin data class, όλα τα πεδία στον πρωτεύοντα κατασκευαστή σειριοποιούνται από προεπιλογή. Αν ένα πεδίο περιέχει ευαίσθητα δεδομένα (κωδικό, διακριτικό), πρέπει να το επισημάνετε με @Transient ή να το αφαιρέσετε από τον πρωτεύοντα κατασκευαστή. Το @Transient εξαιρεί εντελώς το πεδίο από το JSON, αλλά στον κατασκευαστή μπορεί να προκαλέσει σφάλμα — καλύτερα να ορίζετε τέτοιο πεδίο στο σώμα της κλάσης με @Transient.

Τρίτο λάθος — πολυμορφική σειριοποίηση χωρίς sealed class. Αν χρησιμοποιείτε open class αντί για sealed, το kotlinx.serialization απαιτεί ρητή καταχώρηση όλων των απογόνων στο serializersModule. Σε αντίθεση με το sealed class, όπου ο μεταγλωττιστής γνωρίζει όλους τους απογόνους, το open class επιτρέπει αυθαίρετη επέκταση — η βιβλιοθήκη δεν μπορεί να προσδιορίσει αυτόματα όλους τους υποτύπους. Η καταχώρηση γίνεται μέσω Json { serializersModule = SerializersModule { polymorphic(Base::class) { subclass(Derived::class) } } }.

Σφάλμα έκδοσης βιβλιοθήκης

Η έκδοση του kotlinx.serialization πρέπει να είναι συμβατή με την έκδοση Kotlin. Η JetBrains δημοσιεύει πίνακα συμβατότητας: kotlinx-serialization 1.6.x είναι συμβατή με Kotlin 1.9.x, 1.7.x — με Kotlin 2.0.x και 2.1.x. Η ασυμφωνία εκδόσεων προκαλεί αινιγματικά σφάλματα μεταγλώττισης όπως „Symbol ‘serializer’ is missing”. Πάντα ελέγχετε την τρέχουσα έκδοση στο mavenCentral ή στο αποθετήριο GitHub του έργου.