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

الأجزاء والتوجيهات والأنواع المجردة

ركب اختيارات معاد استخدامها وتعامل مع الواجهات والاتحادات دون خلط العرض الشرطي بالتفويض.

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

في هذه الصفحة

أهداف الدرس

توقع توسيع الأجزاء وإدراج الحقول شرطياً.
اختر الحقول الخاصة بالنوع من الإخراج المجرد بأمان.

أعد استخدام اختيار لا كائن استجابة

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

وسع الجزء ذهنياً

افترض Course بموصفي id وtitle غير null وsummary يقبلها. يساهم الجزء بـid وtitle حيث ينشر في موضع متوافق. تضيف العملية summary منفصلة فيرى المراجع المشترك وما يخص الشاشة. لا يعني دمج الحقول المتوافقة تكرار كتابات مستقلة؛ فهذه اختيارات قراءة. تحقق من الوثيقة المركبة لأن أجزاء مقبولة منفردة قد تتعارض في الأسماء أو الوسائط أو شروط النوع.

graphql اختيار بطاقة قابل لإعادة الاستخدام

fragment CardFields on Course { id title }
query CourseDetails($id: ID!) {
  course(id: $id) { ...CardFields summary }
}

يتضمن الاختيار id وtitle وsummary. الجزء تركيب للوثيقة وليس مفتاح رد إضافياً باسم CardFields.

يبقى الإدراج الشرطي اختيار العميل

تتحكم @include و@skip المضمنتان بمشاركة حقل أو جزء في التنفيذ وفق Boolean. لا تمنحان الوصول أو تمنعانه على الخادم، لأن المستدعي يستطيع تغيير المتغير وطلب الحقل. يجب بقاء التفويض في سياسة التطبيق. يغيب الحقل المتخطى عن الرد ولا يلزم ظهوره بـnull. ينبغي أن تعكس أنواع العميل والواجهة الفرق. تحتاج التوجيهات المخصصة دعماً تنفيذياً؛ فتعريف توجيه يبدو للتفويض لا يفرضه.

تفرع وفق النوع الفعلي

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

graphql اختيارات بحث خاصة بالنوع

union SearchResult = Course | Author

query SearchCards($text: String!) {
  search(text: $text) {
    __typename
    ... on Course { id title }
    ... on Author { id displayName }
  }
}

تعرض نتيجة Course حقل title وAuthor حقل displayName. يجب أيضاً تعريف الكائنين وQuery.search قبل التحقق.

افحص الكلفة والتوافق بعد التركيب

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

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

يتوقع اسم الجزء في JSON

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

تستخدم @include لضبط الوصول

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

يختار حقل اتحاد بلا شرط نوع

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

اختبر فهمك

1. هل تمنع summary @include(if: $show) مستخدماً ممنوعاً من القراءة؟

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

لا، يختار المستدعي المتغير أو يرسل وثيقة أخرى. يتحكم التوجيه بالإدراج فقط. ضع قرار الظهور في سياسة الخادم المشتركة وطبقها على كل المسارات. اختبر أن false تحذف المفتاح وأن true تخضع للتفويض.

2. يضيف اتحاد البحث Video. ماذا يراجع العميل والمخطط؟