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 ভersioning-এর কারণে 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 রিপোজিটরিতে সর্বশেষ সংস্করণ চেক করুন।