kotlinx.serialization: یہ کیا ہے، یزدگشتیاں اور JSON میں سیریلائیزیشن

kotlinx.serialization کیا ہے

kotlinx.serialization JetBrains کے ذریعے سرکاری Kotlin ایکو سسٹم کے حصے کے طور پر تیار کردہ 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 میں پلگ ان اور انحصارات شامل کریں۔ Kotlin کے ورژن سے مماثل org.jetbrains.kotlin.plugin.serialization پلگ ان کوڈ جنریشن کو چالو کرتا ہے۔ 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 میں سب سے مقبول فارمیٹ ہے۔ کسی آبجیکٹ کو سیریلائز کرنے کے لیے، data class پر @Serializable یزدگشتی لگائیں اور Json.encodeToString() کو کال کریں۔ ڈی سیریلائیزیشن کے لیے، قسم کی وضاحت کے ساتھ Json.decodeFromString() کو کال کریں۔ لائبریری خود بخود null فیلڈز، فہرستیں، منڈھلے آبجیکٹ اور enum کو ہینڈل کرتی ہے۔ جب تک دوسری صورت نہ کہی جائے، کلاس کے تمام فیلڈز پہلے سے طے شدہ طور پر لازمی ہیں۔

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 ریپازٹری پر ہمیشہ تازہ ترین ورژن چیک کریں۔