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

عقود الرسم البياني ودورة العملية

افصل المخطط والوثيقة التنفيذية والنقل وبيانات التطبيق قبل تنفيذ الرسم.

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

في هذه الصفحة

أهداف الدرس

تتبع التحليل والتحقق وإكراه المتغيرات والتنفيذ لطلب اصطناعي.
اشرح لماذا لا يثبت اختيار الحقول كفاءة قاعدة البيانات أو الصلاحية.

ابدأ بقدرة للتطبيق

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

اقرأ عقد مخطط صغيراً

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

graphql مخطط بوابة اصطناعي

type Query { course(id: ID!): Course }
type Course { id: ID!, title: String! }

يسمح المخطط بطلب course(id: "c1") مع id وtitle؛ ولا توجد نتيجة بيانات قبل أن يوفر محلل الحقل قيمة.

ميز رفض الطلب عن فشل الحقل

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

توقع شكل الاستجابة المختار فقط

افترض أن العينة الاصطناعية المسموح بها c1 تحمل العنوان Graph foundations. تطلب العملية العنوان وتستبعد id عمداً. يتبع الرد الاختيار لا كل خصائص سجل المصدر. قد يحتاج الخادم معرفاً داخلياً لعمله دون عرضه في النتيجة. النتيجة مستنتجة من العينة وليست دليلاً على تشغيل. تسهل تسمية العملية فهم التتبع دون تسجيل متغيرات خاصة أو الجسم كله.

graphql حقل مختار واحد

query CourseCard {
  course(id: "c1") { title }
}

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

{"data":{"course":{"title":"Graph foundations"}}}

للعينة المحددة يحتوي كائن course على title وحده، ويمثل data الغلاف المعتاد لاستجابة GraphQL.

اجعل الأداء والصلاحية صريحين

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

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

يصل حقل مجهول إلى التخزين

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

تصبح كل خصائص السجل عامة

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

يعامل المعرف الصحيح كصلاحية

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

اختبر فهمك

1. يختار الاستعلام title فقط لكن المحلل يجلب السجل كله. ماذا تستنتج عن الكفاءة؟

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

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

2. صنف اسم حقل غير صحيح ومهلة أثناء تحليل عنوان صحيح.