Kotlin Academy · درس

تفاوض المحتوى وkotlinx.serialization

اضبط تسلسل JSON وألغِ تسلسل أجسام الطلبات تلقائيًا.

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

ما هو تفاوض المحتوى؟

تفاوض المحتوى هو آلية HTTP التي يتفق من خلالها العميل والخادم على تنسيق جسم الاستجابة. يرسل العميل ترويسة Accept، ثم يختار الخادم التنسيق الأفضل تطابقًا. تعمل إضافة ContentNegotiation في Ktor على أتمتة ذلك.

إضافة التبعيات

أضف إضافة ContentNegotiation ومحوّل JSON الخاص بـ kotlinx.serialization:

dependencies {
    implementation("io.ktor:ktor-server-content-negotiation:2.3.12")
    implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.12")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
}

تثبيت ContentNegotiation

ثبّت الإضافة في وحدة Application وسجّل محوّل JSON:

import io.ktor.server.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*

fun Application.configureSerialization() {
    install(ContentNegotiation) {
        json()
    }
}

فئات البيانات @Serializable

أضف التعليق التوضيحي @Serializable من kotlinx.serialization إلى فئات البيانات. وتولّد إضافة مترجم Kotlin المُسلسِل أثناء وقت الترجمة — من دون الحاجة إلى الانعكاس أثناء التشغيل:

import kotlinx.serialization.Serializable

@Serializable
data class User(val id: Long, val name: String, val email: String)

إرسال كائن قابل للتسلسل

بعد تثبيت ContentNegotiation، مرّر أي كائن @Serializable إلى call.respond(). ويحوّله Ktor تلقائيًا إلى JSON:

get("/users/{id}") {
    val user = User(1L, "Alice", "alice@example.com")
    call.respond(user)  // serialized to JSON
}

استقبال كائن قابل للتسلسل

استخدم call.receive() لإزالة تسلسل جسم الطلب إلى فئة تحمل التعليق التوضيحي @Serializable. وإذا كان الجسم مشوّهًا، يرمي Ktor الاستثناء ContentTransformationException:

post("/users") {
    val newUser = call.receive<User>()
    call.respond(HttpStatusCode.Created, newUser)
}

تخصيص إعداد JSON

مرّر مثيلًا من Json إلى json() لتخصيص التسلسل: تجاهل المفاتيح غير المعروفة، أو الطباعة المنسّقة، أو استخدام الوضع المتساهل، وغير ذلك:

install(ContentNegotiation) {
    json(Json {
        prettyPrint = true
        isLenient = true
        ignoreUnknownKeys = true
    })
}

أنواع محتوى متعددة

سجّل محوّلات متعددة لدعم أنواع Accept مختلفة. ويختار Ktor أول محوّل يتطابق مع ترويسة Accept الخاصة بالعميل:

install(ContentNegotiation) {
    json()
    // xml() with ktor-serialization-kotlinx-xml if needed
}

تسلسل القوائم والخرائط

غلّف المجموعات داخل كائن استجابة، أو استخدم call.respond(list) مباشرةً. يتعامل kotlinx.serialization مع List وMap والأنواع العامة المتداخلة، ما دامت أنواع العناصر تحمل التعليق التوضيحي @Serializable:

get("/users") {
    val users = listOf(
        User(1, "Alice", "a@example.com"),
        User(2, "Bob", "b@example.com")
    )
    call.respond(users)
}

المُسلسِلات المخصصة

بالنسبة إلى الأنواع التي لا تملكها (مثل java.time.Instant)، طبّق KSerializer وسجّله باستخدام @Serializable(with = MySerializer::class) أو باستخدام وحدة مُسلسِلات سياقية:

val module = SerializersModule {
    contextual(Instant::class, InstantSerializer)
}
install(ContentNegotiation) {
    json(Json { serializersModule = module })
}

معالجة أخطاء فشل إزالة التسلسل

ثبّت إضافة StatusPages لإرجاع استجابة خطأ مناسبة عند فشل call.receive():

install(StatusPages) {
    exception<ContentTransformationException> { call, _ ->
        call.respond(HttpStatusCode.BadRequest, "Invalid request body")
    }
}

تحقق سريع

ما التعليق التوضيحي المطلوب على فئة بيانات Kotlin لجعلها قابلة للتسلسل باستخدام kotlinx.serialization؟

مراجعة: Content Negotiation وkotlinx.serialization

أهم النقاط:

ثبّت ContentNegotiation مع json() لإجراء تسلسل JSON وإلغاء تسلسله تلقائيًا
أضف التعليق التوضيحي @Serializable إلى فئات البيانات
استخدم call.respond(obj) لإجراء تسلسل الكائن وcall.receive() لإلغاء تسلسله
خصّص السلوك باستخدام مثيل Json { ... } يُمرَّر إلى json()
استخدم StatusPages لمعالجة أخطاء إلغاء التسلسل بطريقة مناسبة

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

هل درس «تفاوض المحتوى وkotlinx.serialization» مجاني؟

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

ماذا ستتعلم في «تفاوض المحتوى وkotlinx.serialization»؟

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

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

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

كم من الوقت يستغرق درس «تفاوض المحتوى وkotlinx.serialization»؟

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

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

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

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

إعداد مشروع Ktor: ‏embeddedServer ووحدات Application
التوجيه والمعاملات ذات الأنواع
تفاوض المحتوى وkotlinx.serialization
إضافات المصادقة: JWT وSession

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