Kotlin Academy · درس

إعداد kotlinx.serialization

أضيفوا الإضافة

إعداد kotlinx.serialization درس مجاني في Kotlin Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Kotlin Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Kotlin Academy 4 دروس في المجموع.

ما هي kotlinx.serialization؟

‏kotlinx.serialization هي مكتبة Kotlin الرسمية لتحويل الكائنات من وإلى تنسيقات مثل JSON.

مكتوبة بالكامل بلغة Kotlin وجاهزة للعمل على منصات متعددة
توليد الشيفرة وقت الترجمة، من دون استخدام الانعكاس
تتولى JetBrains صيانتها

وهي تعمل باستخدام إضافة للمترجم إلى جانب مكتبة وقت التشغيل.

لماذا نحتاج إلى إضافة للمترجم؟

على خلاف المكتبات التي تعتمد على الانعكاس، تنشئ kotlinx.serialization المُسلسِلات وقت الترجمة.

أسرع، ولا تفرض تكلفة الانعكاس وقت التشغيل
تعمل على Kotlin/Native وJS، حيث تكون إمكانات الانعكاس محدودة
آمنة من ناحية الأنواع ويتحقق منها المترجم

ولهذا يجب تطبيق إضافة kotlin-serialization، وليس الاكتفاء بإضافة اعتماد.

تطبيق الإضافة (Kotlin DSL)

في build.gradle.kts، طبّقوا إضافة التسلسل باستخدام الإصدار نفسه المستخدم في إضافة Kotlin.

plugins {
    kotlin("jvm") version "2.0.0"
    kotlin("plugin.serialization") version "2.0.0"
}

إضافة اعتماد وقت التشغيل

تنشئ الإضافة الشيفرة، لكنكم تحتاجون أيضًا إلى مكتبة وقت تشغيل JSON.

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
}

توافق الإصدارات مهم

يجب أن يتطابق إصدار plugin.serialization تمامًا مع إصدار مترجم Kotlin. أما مكتبة وقت التشغيل فلها إصدار مستقل.

إصدار الإضافة = إصدار Kotlin، مثل 2.0.0
إصدار وقت التشغيل مستقل، مثل 1.7.1

تؤدي إصدارات الإضافة وKotlin غير المتطابقة إلى أخطاء إنشاء غامضة.

تنسيقات أخرى

يُعد JSON التنسيق الأكثر شيوعًا، لكن kotlinx.serialization تدعم تنسيقات أخرى من خلال artifacts إضافية:

kotlinx-serialization-json — JSON
kotlinx-serialization-cbor — CBOR ثنائي
kotlinx-serialization-protobuf — Protocol Buffers

أضيفوا فقط artifacts الخاصة بالتنسيقات التي تحتاجون إليها.

المكافئ باستخدام Groovy DSL

إذا كان مشروعكم يستخدم Groovy في build.gradle بدلًا من Kotlin DSL، فسيبدو الإعداد كما يلي.

// build.gradle (Groovy)
plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.0.0'
    id 'org.jetbrains.kotlin.plugin.serialization' version '2.0.0'
}

dependencies {
    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1'
}

نقطة الدخول إلى Json

بعد الإعداد، استخدموا الكائن Json من kotlinx.serialization.json بوصفه نقطة الدخول الرئيسية للترميز وفك الترميز.

import kotlinx.serialization.json.Json

val format = Json
// format.encodeToString(...) / format.decodeFromString(...)

مثال عملي مختصر

إليكم أصغر مثال متكامل يمكن تشغيله بعد إعداد الإضافة ومكتبة وقت التشغيل.

import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json

@Serializable
data class City(val name: String, val population: Int)

fun main() {
    val city = City("Istanbul", 15000000)
    val json = Json.encodeToString(city)
    println(json)
}

إعداد المشاريع متعددة المنصات

في مشروع Kotlin Multiplatform، أضيفوا مكتبة وقت التشغيل إلى commonMain حتى تشترك فيها جميع المنصات المستهدفة.

sourceSets {
    val commonMain by getting {
        dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
        }
    }
}

أخطاء الإعداد الشائعة

انتبهوا إلى المشكلات المتكررة التالية:

نسيان الإضافة — يظهر الخطأ Serializer has not been found
عدم تطابق إصدار الإضافة مع إصدار Kotlin
إضافة مكتبة وقت التشغيل من دون الإضافة، أو العكس
غياب استيراد encodeToString

تحقّق سريع

لماذا تتطلب kotlinx.serialization إضافة مترجم لـ Gradle؟

مراجعة

أعددتم kotlinx.serialization من خلال:

تطبيق إضافة kotlin("plugin.serialization") المطابق لإصدار Kotlin المستخدم
إضافة اعتماد وقت التشغيل kotlinx-serialization-json
استخدام الكائن Json بوصفه نقطة الدخول

بعد ذلك ستضيفون التعليقات التوضيحية إلى فئات النماذج باستخدام @Serializable.

الأسئلة الشائعة

هل درس «إعداد kotlinx.serialization» مجاني؟

نعم — نص درس «إعداد kotlinx.serialization» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Kotlin Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Kotlin Academy 4 دروس في المجموع.

ماذا ستتعلم في «إعداد kotlinx.serialization»؟

أضيفوا الإضافة تتمرن على Kotlin Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Kotlin Academy؟

لا تُشترط خبرة سابقة. Kotlin Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «إعداد kotlinx.serialization»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Kotlin Academy هذا؟

نعم. كل درس في Kotlin Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Kotlin Academy