GraphQL / الأساسي: عقود اللغة والرد / الدرس 3

الاستعلامات والوسائط والمتغيرات

ابن عمليات مسماة قابلة لإعادة الاستخدام وميز الإدخال المحذوف عن null الصريحة.

وقت القراءة التقريبي: 3 دقيقةتاريخ مراجعة المحتوى 2026-10-28

في هذه الصفحة

أهداف الدرس

عرف متغيرات تناسب الوسائط وافصل القيم عن نص الوثيقة.
توقع افتراضات الوسائط والإدخال المطلوب ومفاتيح الأسماء البديلة.

حافظ على بنية عملية ثابتة

يختار الاستعلام الحقول ويمرر وسائط مسماة. يعرف اسم العملية حالة الاستخدام وتحمل المتغيرات القيم المتغيرة. يسهل الفصل مراجعة الوثائق وتخزينها وتعريفها في التتبع ويجنب بناء الصياغة بدمج نص المستخدم. لا تعقم المتغيرات SQL تلقائياً ولا تفرض التفويض، بل توفر حد إدخال ذا أنواع. على المحلل استعمال معاملات المصدر الآمنة ونطاق المستدعي المسموح.

اربط الوثيقة بخريطة JSON

افترض أن course(id: ID!) يعيد المقرر الاصطناعي المرئي c1. يطلب تعريف المتغير ID غير null وتوفره خريطة JSON. يعاد استعمال الوثيقة بمعرف مسموح آخر دون تغيير نصها. يفشل غياب المتغير المطلوب أثناء إكراه الإدخال قبل تنفيذ الحقول. احفظ الأنواع عند تسلسل JSON؛ فالمتغير Boolean يحتاج true لا السلسلة "true". تختلف رسائل الخطأ بين المكتبات فصنف المرحلة والحقل.

graphql وثيقة عملية قابلة لإعادة الاستخدام

query CourseCard($id: ID!) {
  course(id: $id) { id title }
}

أرسل variables بالقيمة {"id":"c1"}. الوثيقة والمتغيرات عضوان منفصلان في جسم طلب HTTP.

الحذف ليس null الصريحة

قد تكون للوسائط والمتغيرات الاختيارية افتراضات. يسمح الحذف بتطبيقها، أما تقديم null فهو قيمة وليس طلباً للافتراض. يهم ذلك خصوصاً في التحديث حيث يعني الحذف الإبقاء وnull المسح. يجب أن يناسب نوع المتغير موضع الوسيط وفق قواعد المواصفة والافتراضات المعنية. فضل تعريفات واضحة متوافقة في العمليات الأساسية بدلاً من استثناءات دقيقة دون اختبارات.

استعمل أسماء بديلة لاختلاف الوسائط

تغير الأسماء البديلة مفاتيح الرد لا هوية الحقل أو قواعد صلاحياته. اختيار course مرتين بمعرفين مختلفين تحت الاسم نفسه يسبب تعارض دمج. توضح الأسماء المختلفة موضعين للنتيجة. قد يحلهما الخادم بالتوازي، فلا تستنتج ترتيب التنفيذ من موضعهما. تفترض العينة ظهور الكائنين وعنوانيهما. إن تعذر أحدهما فقد يكون null دون حذف الآخر.

graphql بحثان باسمي استجابة مختلفين

query CompareCards {
  first: course(id: "c1") { title }
  second: course(id: "c2") { title }
}

الناتج المتوقع

{"data":{"first":{"title":"Graph foundations"},"second":{"title":"Graph practice"}}}

للعنوانين المحددين يظهر first وsecond كمفتاحين مختلفين. الاسم البديل ليس حد تخزين أو وصول.

راجع الوثيقة مع عينات المتغيرات

قد تنجح وثيقة بعينة وتفشل بمتغير مفقود أو نوع JSON خاطئ أو حد عمل متجاوز. اختبر المطلوب والمحذوف وnull والقيم الحدية قرب العملية. إن احتوت الوثيقة عمليات متعددة وجب اختيار المقصودة بالاسم. لا تضع قيماً حساسة في URL لتسهيل الفحص لأن السجلات والتاريخ قد تحفظها. يحتاج النقل وصحة الوثيقة مراجعتين منفصلتين.

الأخطاء الشائعة وإصلاحها

يستخدم متغير String حيث يطلب ID!

لماذا يحدث؟: اختلط تشابه التسلسل بتوافق الأنواع.
كيف تصلحه؟: عرف المتغير بالنوع المتوافق المطلوب.
كيف تتجنب تكراره؟: تحقق من الوثائق بجانب فحص JSON.

تمسح null الصريحة حقلاً دون توقع

لماذا يحدث؟: استخدم العميل null بمعنى الحذف.
كيف تصلحه؟: احذف العضو عندما يعني ذلك الإبقاء وفق العقد.
كيف تتجنب تكراره؟: اختبر الحذف وnull والقيمة مستقلة.

يتعارض حقلان بوسيطين مختلفين

لماذا يحدث؟: يحمل الاختياران مفتاح الرد نفسه.
كيف تصلحه؟: ضع اسمين بديلين واضحين.
كيف تتجنب تكراره؟: راجع دمج الحقول عند تركيب الوثائق.

اختبر فهمك

1. لـlimit الاختياري افتراض 20. هل إرسال null كحذفه؟

اعرض الحل المشروح

لا؛ يسمح الحذف بالافتراض، وnull المقدمة قيمة يجب أن تناسب العقد والسياسة. اختبر الحذف وnull والصفر والقيمة الموجبة. إن منعتها الواجهة فعبر عن ذلك بالمخطط والتحقق بدلاً من الاستبدال الصامت في العملاء.

2. لماذا لا تجعل المتغيرات SQL المبنية نصياً آمنة تلقائياً؟