kotlinx.serialization: यह क्या है, एनोटेशन और JSON में सीरियलाइज़ेशन

kotlinx.serialization क्या है

kotlinx.serialization Kotlin के लिए एक अंतर्निहित सीरियलाइज़ेशन लाइब्रेरी है, जिसे JetBrains द्वारा आधिकारिक Kotlin इकोसिस्टम के भाग के रूप में विकसित किया गया है। तृतीय-पक्ष समाधानों (Gson, Moshi, Jackson) से इसका मुख्य अंतर यह है कि यह रनटाइम पर रिफ्लेक्शन का उपयोग नहीं करती। इसके बजाय, सीरियलाइज़र कोड Kotlin Symbol Processing (KSP) या Kotlin कंपाइलर प्लगइन का उपयोग करके कंपाइल समय पर जनरेट होता है। यह Gson की तुलना में 3–5 गुना तक प्रदर्शन लाभ प्रदान करता है और टाइप सुरक्षा सुनिश्चित करता है।

लाइब्रेरी आधिकारिक रूप से चार फ़ॉर्मेट सपोर्ट करती है: 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 इंटरफ़ेस को लागू करता है। तीसरे चरण में, जनरेट किया गया कोड प्रोजेक्ट के सोर्स कोड के साथ कंपाइल होता है। परिणामस्वरूप, ये कोई भी चरण एप्लिकेशन रनटाइम के दौरान निष्पादित नहीं होता।

जनरेट किया गया सीरियलाइज़र रिफ्लेक्शन के बिना, अपने गेटर्स और सेटर्स के माध्यम से सीधे क्लास के फ़ील्ड के साथ काम करता है। इसका मतलब है कि private मॉडिफ़ायर वाले फ़ील्ड भी सीरियलाइज़ होते हैं यदि वे @Serializable से चिह्नित हैं। इस दृष्टिकोण का प्रदर्शन मैन्युअल सीरियलाइज़ेशन के करीब है: सरल क्लास (5–10 फ़ील्ड) के लिए, सीरियलाइज़ेशन समय 10–50 माइक्रोसेकंड है; जटिल ऑब्जेक्ट ग्राफ़ के लिए, प्रति 1000 ऑब्जेक्ट पर 200 माइक्रोसेकंड तक।

Android या Kotlin/JVM प्रोजेक्ट में लाइब्रेरी जोड़ने के लिए, आपको build.gradle.kts में प्लगइन और निर्भरताएँ जोड़नी होंगी। org.jetbrains.kotlin.plugin.serialization प्लगइन, Kotlin के संस्करण से मेल खाता हुआ, कोड जनरेशन को सक्रिय करता है। kotlinx-serialization-json लाइब्रेरी डिपेंडेंसीज़ सेक्शन में 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 में सबसे लोकप्रिय फ़ॉर्मेट है। किसी ऑब्जेक्ट को सीरियलाइज़ करने के लिए, data class पर @Serializable एनोटेशन लगाएँ और 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")
    )

    // prettyPrint के साथ JSON सीरियलाइज़ेशन
    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
}

उदाहरण सीरियलाइज़ेशन और डीसीरियलाइज़ेशन के मूल चक्र को दर्शाता है। @Serializable एनोटेशन वाली data class Project स्वचालित रूप से encodeToString और decodeFromString प्राप्त करती है। isActive फ़ील्ड का डिफ़ॉल्ट मान true है — यदि JSON में यह फ़ील्ड गायब है, तो डिफ़ॉल्ट का उपयोग किया जाता है। यदि ignoreUnknownKeys = true के बिना JSON में अज्ञात फ़ील्ड आते हैं, तो 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। अतिरिक्त: JSON में फ़ील्ड का नाम सेट करने के लिए @SerialName (यदि यह Kotlin नाम से भिन्न है), सीरियलाइज़ेशन से फ़ील्ड को बाहर करने के लिए @Transient, JSON में मौजूद रहने वाले फ़ील्ड के लिए @Required, डिफ़ॉल्ट मान के साथ भी फ़ील्ड को सीरियलाइज़ करने के लिए @EncodeDefault।

@SerialName एनोटेशन API के साथ काम करते समय महत्वपूर्ण है जहाँ फ़ील्ड नाम snake_case में हैं, जबकि Kotlin शैली camelCase है। उदाहरण के लिए, सर्वर “user_id” भेजता है, जबकि Kotlin कोड userId का उपयोग करता है। @SerialName(“user_id”) अतिरिक्त मैपर्स के बिना इस समस्या को हल करता है। @Transient उन फ़ील्ड के लिए उपयोगी है जिन्हें सर्वर को भेजने की आवश्यकता नहीं है — उदाहरण के लिए, अस्थायी गणना मान या कैश।

Nullable फ़ील्ड के विकल्प के रूप में @Required

डिफ़ॉल्ट रूप से, kotlinx.serialization में सभी फ़ील्ड अनिवार्य हैं। यदि कोई फ़ील्ड JSON में अनुपस्थित हो सकता है, तो इसे nullable (String?) बनाएँ या डिफ़ॉल्ट मान सेट करें (val name: String = “”)। हालाँकि, ऐसी स्थितियाँ होती हैं जहाँ कोई फ़ील्ड Kotlin में non-nullable है लेकिन API वर्ज़निंग के कारण JSON में गायब हो सकता है। इस मामले में, @Required फ़ील्ड अनुपस्थित होने पर SerializationException फेंकता है, जबकि डिफ़ॉल्ट मान इसे त्रुटि के बिना भरता है।

कस्टम सीरियलाइज़र: 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("Release", 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 बिना .proto के सीधे @Serializable से Kotlin क्लास जनरेट करता है। यह विकास को सरल बनाता है: बस data class को एनोटेट करें और ProtoBuf.encodeToByteArray() का उपयोग करें। CBOR विशेष रूप से Android फ्रेमवर्क के लिए प्रासंगिक है जब आपको NFC या BLE के माध्यम से कॉम्पैक्ट बाइनरी डेटा स्थानांतरित करने की आवश्यकता होती है। CBOR संदेश समान डेटा सेट के लिए JSON से औसतन 20–30% छोटे होते हैं।

प्रोजेक्ट के लिए फ़ॉर्मेट चुनना

मोबाइल ऐप में REST API के लिए, JSON सबसे अच्छा विकल्प है — इसे अतिरिक्त टूल के बिना डीबग किया जा सकता है, लॉग में पढ़ा जा सकता है, और किसी भी बैकएंड के साथ संगत है। यदि ऐप माइक्रोसर्विसेज़ के बीच बड़ी मात्रा में डेटा (सैकड़ों मेगाबाइट) स्थानांतरित करता है, तो ProtoBuf बाइनरी एन्कोडिंग के कारण 5x तक गति लाभ प्रदान करता है। फ़ाइलों में सेटिंग्स संग्रहीत करने के लिए, HOCON या JSON का उपयोग करें। सख्त ट्रैफ़िक सीमा वाले उपकरणों (IoT सेंसर) के लिए, CBOR का उपयोग करें।

kotlinx.serialization के साथ काम करते समय सामान्य गलतियाँ

पहली गलती — डीसीरियलाइज़ेशन के दौरान अज्ञात कुंजियों को अनदेखा करना। यदि सर्वर एक नया फ़ील्ड जोड़ता है और आपके पास ignoreUnknownKeys = false है, तो एप्लिकेशन SerializationException के साथ क्रैश हो जाएगा। यह फ़्लैग डिफ़ॉल्ट रूप से बंद है। समाधान: API परिवर्तनों के प्रति लचीला होने के लिए प्रोडक्शन कोड के लिए हमेशा Json { ignoreUnknownKeys = true } सेट करें।

दूसरी गलती — data class में internal या private फ़ील्ड का सीरियलाइज़ेशन। Kotlin data class में, प्राइमरी कंस्ट्रक्टर के सभी फ़ील्ड डिफ़ॉल्ट रूप से सीरियलाइज़ होते हैं। यदि किसी फ़ील्ड में संवेदनशील डेटा (पासवर्ड, टोकन) है, तो इसे @Transient से चिह्नित किया जाना चाहिए या प्राइमरी कंस्ट्रक्टर से बाहर निकाला जाना चाहिए। @Transient फ़ील्ड को JSON से पूरी तरह बाहर करता है, लेकिन कंस्ट्रक्टर के अंदर यह त्रुटि पैदा कर सकता है — ऐसे फ़ील्ड को @Transient के साथ क्लास बॉडी में परिभाषित करना बेहतर है।

तीसरी गलती — sealed class के बिना पॉलीमॉर्फ़िक सीरियलाइज़ेशन। यदि आप sealed के बजाय open class का उपयोग करते हैं, तो 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” जैसी अस्पष्ट कंपाइलेशन त्रुटियाँ होती हैं। हमेशा Maven Central या प्रोजेक्ट के GitHub रिपॉज़िटरी पर नवीनतम संस्करण जाँचें।