التسلسل (kotlinx) لـ Kotlin: دليل كامل مع أمثلة

ما هو kotlinx.serialization ولماذا هو مطلوب؟

\n\n

kotlinx.serialization هي مكتبة رسمية من JetBrains لتسلسل وإلغاء تسلسل البيانات في Kotlin. توفر طريقة قوية وآمنة من حيث النوع ومتعددة المنصات لتحويل كائنات Kotlin إلى صيغ مختلفة (JSON، Protobuf، CBOR، YAML وغيرها) والعكس.

\n\n

الأسباب الرئيسية لاستخدام هذه المكتبة:

\n

\n
• تعدد المنصات: تعمل على JVM، JS، Native (iOS، Android، Desktop).
\n
• أمان النوع: يتم التحقق من التسلسل في مرحلة الترجمة، مما يمنع الأخطاء أثناء التنفيذ.
\n
• الأداء: تستخدم الانعكاس فقط عند الضرورة (عبر إضافة المترجم).
\n
• المرونة: تدعم المسلسلات المخصصة، تعدد الأشكال، الحقول الاختيارية وأكثر من ذلك بكثير.
\n
• التكامل مع Kotlin: تستخدم بالكامل إمكانيات اللغة (data class، sealed class، null safety).
\n

\n\n

التثبيت والإعداد

\n\n

لاستخدام kotlinx.serialization، يجب إضافة إضافة المترجم والتبعية إلى مشروعك.

\n\n

1. إضافة الإضافة (build.gradle.kts):

\n

plugins {\n    kotlin("jvm") version "1.9.0" // أو إصدار Kotlin الخاص بك\n    kotlin("plugin.serialization") version "1.9.0"\n}

\n\n

2. إضافة التبعية:

\n

dependencies {\n    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.2")\n}

\n\n

3. لـ Maven (pom.xml):

\n

<plugin>\n    <groupId>org.jetbrains.kotlin</groupId>\n    <artifactId>kotlin-maven-plugin</artifactId>\n    <version>1.9.0</version>\n    <configuration>\n        <pluginOptions>\n            <option>plugin:org.jetbrains.kotlin.plugin.serialization</option>\n        </pluginOptions>\n    </configuration>\n</plugin>\n\n<dependency>\n    <groupId>org.jetbrains.kotlinx</groupId>\n    <artifactId>kotlinx-serialization-json</artifactId>\n    <version>1.6.2</version>\n</dependency>

\n\n

بداية سريعة: المثال الأول

\n\n

import kotlinx.serialization.Serializable\nimport kotlinx.serialization.json.Json\nimport kotlinx.serialization.encodeToString\nimport kotlinx.serialization.decodeFromString\n\n// 1. تعريف الفئة القابلة للتسلسل\n@Serializable\ndata class User(val name: String, val age: Int, val email: String? = null)\n\nfun main() {\n    // 2. إنشاء كائن\n    val user = User("Alice", 30, "alice@example.com")\n\n    // 3. تسلسل إلى JSON\n    val jsonString = Json.encodeToString(user)\n    println("JSON المسلسل: $jsonString")\n\n    // 4. إلغاء التسلسل مرة أخرى\n    val decodedUser = Json.decodeFromString<User>(jsonString)\n    println("الكائن بعد إلغاء التسلسل: $decodedUser")\n}

\n\n

المخرجات:

\n

JSON المسلسل: {"name":"Alice","age":30,"email":"alice@example.com"}\nالكائن بعد إلغاء التسلسل: User(name=Alice, age=30, email=alice@example.com)

\n\n

الطرق والوظائف الأساسية (8+)

\n\n

1. Json.encodeToString()

\n

ما تفعله: تسلسل كائن Kotlin إلى سلسلة JSON.

\n

المعلمات:

\n

\n
• value (T) — الكائن المراد تسلسله.
\n
• serializer (Serializer<T>?) — مسلسل مخصص اختياري.
\n

\n

val user = User("Bob", 25)\nval json = Json.encodeToString(user)\nprintln(json) // {"name":"Bob","age":25}

\n\n

2. Json.decodeFromString()

\n

ما تفعله: إلغاء تسلسل سلسلة JSON إلى كائن Kotlin.

\n

المعلمات:

\n

\n
• string (String) — سلسلة JSON.
\n
• des