Kotlin Academy · درس

Serializers مخصصة

عالجوا الأنواع الخاصة

الدرس 4 من 413 خطوة

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

لماذا نحتاج إلى مُسلسِلات مخصّصة؟

لا تملك بعض الأنواع مُسلسِلًا مدمجًا، مثل java.util.Date وLocalDate وUUID أو الأنواع القادمة من مكتبات خارجية.

يحدّد المُسلسِل المخصّص كيفية تحويل هذا النوع من وإلى تمثيل قابل للتسلسل.

واجهة KSerializer

يطبّق المُسلسِل المخصّص KSerializer<T> مع ثلاثة أعضاء: descriptor وserialize وdeserialize.

import kotlinx.serialization.KSerializer
import kotlinx.serialization.descriptors.SerialDescriptor
import kotlinx.serialization.encoding.Decoder
import kotlinx.serialization.encoding.Encoder

مُسلسِل لـ LocalDate

حوّلوا LocalDate من وإلى سلسلة بتنسيق ISO. ويصرّح الواصف بأنه سلسلة بدائية.

import java.time.LocalDate
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

object LocalDateSerializer : KSerializer<LocalDate> {
    override val descriptor: SerialDescriptor =
        PrimitiveSerialDescriptor("LocalDate", PrimitiveKind.STRING)
    override fun serialize(encoder: Encoder, value: LocalDate) =
        encoder.encodeString(value.toString())
    override fun deserialize(decoder: Decoder): LocalDate =
        LocalDate.parse(decoder.decodeString())
}

استخدام @Serializable(with = ...)

طبّقوا المُسلسِل على خاصية محدّدة باستخدام @Serializable(with = ...).

import java.time.LocalDate
import kotlinx.serialization.Serializable

@Serializable
data class Event(
    val name: String,
    @Serializable(with = LocalDateSerializer::class)
    val date: LocalDate
)

‏@UseSerializers على مستوى الملف

لتجنب إضافة التعليق التوضيحي إلى كل خاصية، صرّحوا عن المُسلسِلات مرة واحدة لكل ملف باستخدام @file:UseSerializers.

@file:UseSerializers(LocalDateSerializer::class)

import kotlinx.serialization.UseSerializers
import java.time.LocalDate
import kotlinx.serialization.Serializable

@Serializable
data class Event(val name: String, val date: LocalDate)

التسلسل السياقي

سجّلوا المُسلسِلات بشكل عام في الوحدة النمطية Json { }، ثم ضعوا علامة @Contextual على الخصائص. ويُحلّ المُسلسِل وقت التشغيل من الوحدة النمطية.

import kotlinx.serialization.Contextual
import kotlinx.serialization.Serializable
import java.time.LocalDate

@Serializable
data class Event(val name: String, @Contextual val date: LocalDate)

تسجيل SerializersModule

أنشئوا وحدة تربط النوع بالمُسلسِل الخاص به، ثم مرّروها إلى Json.

import kotlinx.serialization.json.Json
import kotlinx.serialization.modules.SerializersModule
import java.time.LocalDate

val module = SerializersModule {
    contextual(LocalDate::class, LocalDateSerializer)
}
val json = Json { serializersModule = module }

المُسلسِلات المركّبة

بالنسبة إلى الأنواع متعددة الحقول، استخدموا encodeStructure / decodeStructure مع واصف بنيوي بدلًا من واصف بدائي.

import kotlinx.serialization.descriptors.buildClassSerialDescriptor
import kotlinx.serialization.descriptors.element

val descriptor = buildClassSerialDescriptor("Color") {
    element<Int>("r")
    element<Int>("g")
    element<Int>("b")
}

نمط النوع البديل

ثمة بديل أبسط: سَلْسِلوا فئة بيانات خاصة بديلة تدعمها أداة المترجم مسبقًا، ثم حوّلوا منها وإليها النوع الحقيقي. وهذا يتطلب شيفرة مكررة أقل من الترميز وفك الترميز يدويًا.

import kotlinx.serialization.Serializable

@Serializable
private data class ColorSurrogate(val r: Int, val g: Int, val b: Int)

اختيار الأسلوب المناسب

اختاروا أبسط أسلوب يلائم احتياجاتكم:

  • @Serializable(with=) — خاصية واحدة
  • @UseSerializers — الملف بأكمله
  • @Contextual + module — على مستوى التطبيق، مع حلّ وقت التشغيل
  • النوع البديل — للأنواع المركّبة مع أقل قدر من الشيفرة

الواصف البدائي مقابل الواصف البنيوي

يجب أن يطابق الواصف طريقة الترميز المستخدمة:

  • قيمة واحدة، مثل سلسلة أو عدد صحيح → PrimitiveSerialDescriptor
  • حقول متعددة → buildClassSerialDescriptor

يؤدي عدم التطابق إلى أخطاء تسلسل وقت التشغيل.

تحقّق سريع

تريدون تسلسل LocalDate واحد في صورة سلسلة ISO واحدة. أي واصف مناسب؟

مراجعة

تتعامل المُسلسِلات المخصّصة مع الأنواع التي لا تعرفها الإضافة:

  • طبّقوا KSerializer<T> مع descriptor وserialize وdeserialize
  • طبّقوها باستخدام @Serializable(with=) أو @UseSerializers أو @Contextual مع وحدة نمطية
  • طابقوا نوع الواصف مع طريقة الترميز

وبهذا تكتمل دورة التسلسل.

البدء مجانًا

تعلم Kotlin مع معلم ذكاء اصطناعي — مجانًا

اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.

الدورات
51
الدروس
203

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

هل درس «Serializers مخصصة» مجاني؟

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

ماذا ستتعلم في «Serializers مخصصة»؟

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

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

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

كم من الوقت يستغرق درس «Serializers مخصصة»؟

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

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

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

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

  1. إعداد kotlinx.serialization
  2. الفئات القابلة للتسلسل
  3. ترميز JSON وفك ترميزه
  4. Serializers مخصصة
← العودة إلى Kotlin Academy