GraphQL / الأساسي: عقود اللغة والرد / الدرس 2
الكائنات والقيم القياسية والتعداد وقبول null
اختر أنواع إخراج دقيقة وافهم انتشار null بدلاً من إضافة علامات التعجب بلا تمييز.
في هذه الصفحة
أهداف الدرس
- اقرأ قبول null للقائمة والعنصر منفصلين.
- ميز المعرفات العامة والتعداد المحدود وعقود القيم المخصصة.
افصل الهوية عن القيم المقاسة
يجمع الكائن حقول إخراج مسماة وتنهي القيمة القياسية مسار الاختيار. تشمل القيم المضمنة String وBoolean وInt وFloat وID. تمثل Int عدداً صحيحاً بإشارة من 32 بت، فلا تناسب عداداً ضخماً لمجرد دعم اللغة له. يمثل ID هوية معتمة لا حساباً. يحتفظ العميل بالمعرف دون استنتاج بنية قاعدة البيانات منه. اتفق صراحة على تمثيل المبالغ والتواريخ ودقتها، فاسم النوع لا يقدم دلالات العمل.
اقرأ طبقتي تعريف القائمة
تختلف التعريفات الأربعة في قبول القائمة نفسها أو عناصرها null. تبقى القائمة الفارغة مسموحة حتى مع [String!]!، فعدم قبول null لا يعني وجود عنصر واحد على الأقل. يؤثر ذلك في العرض وانتشار الأخطاء. قد تعني القائمة null عدم توافر بيانات المجموعة، والفارغة بحثاً ناجحاً بلا نتائج مسموحة. وثق المعنى ولا تحول كل null إلى قائمة فارغة فتمحو الفرق بين الفشل والغياب.
type Labels {
a: [String]
b: [String!]
c: [String]!
d: [String!]!
}يسمح a بقائمة وعناصر null؛ ويسمح b بالقائمة null فقط، وc بالعناصر null فقط، وd لا يسمح بأي منهما. وتسمح كلها بـ[].
ينقل عدم قبول null حد الفشل
عندما يعجز التنفيذ عن قيمة حقل لا يقبل null ينتشر الخطأ إلى أقرب أب يقبلها. وإذا لم يوجد قد تصبح data للعملية كلها null. يحسن الوعد تجربة العميل المعتادة لكنه قد يزيد بيانات الأشقاء غير المتاحة عند فشل المصدر. نمذج حدود الفشل المستقلة بعناية؛ فقد يستحق الاسم المحلي الموثوق والتوصية الخارجية المباشرة قبولاً مختلفاً لـnull رغم رغبة المنتج في ظهورهما دائماً.
قيد المفردات دون افتراض ثباتها
يجعل التعداد مفردات المجال الصغيرة قابلة للاكتشاف ويتحقق من القيم القانونية. يحتاج تطور تعداد الإخراج للحذر لأن عميلًا ذا تفريع شامل قد يتلقى قيمة جديدة. يفصل المثال مفردات الآلة عن النص البشري. يحتاج النوع المخصص مثل DateTime إلى إكراه وتسلسل وتوثيق؛ فتعريفه وحده لا ينفذ تنسيق ISO. تستخدم العينة تعداداً للحالة وعنوان عرض للبشر وفق سياسة ترجمة معلنة.
enum PublicationState { DRAFT PUBLISHED ARCHIVED }
type Course {
id: ID!
title: String!
state: PublicationState!
}تكتب PUBLISHED رمز تعداد في الوثيقة وتصبح السلسلة "PUBLISHED" في JSON، وهي منفصلة عن نص العنوان.
اختر الوعود من سلوك الفشل الفعلي
راجع لكل حقل غياب الكائن وإمكان فشل المصدر مستقلاً وما ينبغي أن يعرفه العميل. لا يعفي قبول null من توثيق سلوك الغياب والخطأ. وقد تخفي إضافتها لتسهيل الأنواع المولدة تضخيم الفشل. ضع اختبارات المدى والتسلسل قرب موائم المخطط. إن تجاوزت البيانات مدى Int فاختر تمثيلاً بديلاً موثقاً مع معالجة العميل بدلاً من التقريب أو القطع الصامت.
الأخطاء الشائعة وإصلاحها
تعد القائمة الفارغة مخالفة لنوع لا يقبل null
- لماذا يحدث؟
- اختلط عدد العناصر بقبول null.
- كيف تصلحه؟
- طبق قاعدة عمل إن وجب عنصر واحد على الأقل.
- كيف تتجنب تكراره؟
- اختبر [] وnull وقائمة تتضمن null منفصلة.
يفشل تسلسل عداد ضخم إلى Int
- لماذا يحدث؟
- تتجاوز القيمة عقد 32 بت بإشارة.
- كيف تصلحه؟
- اعتمد تمثيلاً متوافقاً وحدث العملاء.
- كيف تتجنب تكراره؟
- اختبر الحدود العددية لا العينات الصغيرة فقط.
يحذف حقل خارجي الأب كله
- لماذا يحدث؟
- نشر تسلسل عدم قبول null خطأ التنفيذ.
- كيف تصلحه؟
- راجع حد الفشل ومعالجة المصدر.
- كيف تتجنب تكراره؟
- أدرج اختبار فشل مصدر جزئي عند مراجعة المخطط.
اختبر فهمك
1. هل تعيد [ID!]! القيمة [] أو ["c1", null]؟ فسر.
اعرض الحل المشروح
يمكنها إرجاع [] لأن العقد يطلب قائمة وعناصر غير null عند وجودها. لا يسمح بعنصر null. وقد ينشر فشل إكمال العنصر الخطأ عبر القائمة إلى الأب. شرط الحد الأدنى للطول قاعدة تطبيق تختبر مستقلة.
2. يريد العميل المولد منع null في كل الحقول. كيف يرد المراجع؟
اعرض الحل المشروح
راجع ضمانات البيانات والفشل بدلاً من القبول التلقائي. حدد الفشل المستقل الذي يجب أن يحفظ الأب ومعنى الغياب. استخدم الوعد حيث يبرره المصدر واشرح مسار الخطأ والرد الجزئي. سهولة العميل مفيدة لكنها لا تخلق موثوقية مفقودة.
أهم ما تعلمته
- يحدد قبول null حدود الفشل والقيم المعتادة.
- تحتاج الهوية والدقة وتطور التعداد عقوداً صريحة.