GraphQL / الأساسي: عقود اللغة والرد / الدرس 5
الإدخال والطفرات ونتائج المجال
صمم عقد كتابة محدوداً بدلالات تحديث واضحة وميز رفض العمل المتوقع عن فشل التنفيذ.
في هذه الصفحة
أهداف الدرس
- افصل كائنات الإدخال والإخراج وحدد الحذف وnull.
- اشرح تسلسل جذور الطفرات دون افتراض معاملة.
اعرض نية لا تحرير تخزين مطلقاً
تسمي الطفرة تغييراً يدعمه التطبيق مثل publishCourse أو renameCourse، ولا ينبغي قبول كل عمود في قاعدة البيانات. تصف كائنات الإدخال البنية المسموحة ولا يستبدلها نوع كائن إخراج. يترك الإدخال المخصص مجالاً لحقول اختيارية لاحقة ويحفظ معنى العملية. صحة النوع حد أول، وتبقى اختبارات الطول والحالة والملكية والتعارض ضمن تحقق العمل قبل الحفظ.
اجعل دلالات التحديث مرئية
يستخدم الإدخال معرفاً مطلوباً وملخصاً اختيارياً. تنص السياسة على أن الحذف يبقي القديم وnull تمسحه والسلسلة تستبدله بعد التحقق. لا يخترع المخطط تلك السياسة. يجب كشف وجود العضو لا اختبار صدقه الذي يخلط السلسلة الفارغة بالغياب. يعرض الرد الكائن المحدث وقائمة مشاكل متوقعة. هذه خيارات تطبيق لا أسماء إلزامية أو تنفيذ تلقائي لمعاملة.
input EditCourseInput { id: ID!, summary: String }
type Problem { field: String!, code: String! }
type EditCoursePayload { course: Course, problems: [Problem!]! }
type Mutation { editCourse(input: EditCourseInput!): EditCoursePayload! }يفترض الجزء وجود Course. يميز العميل حمولة صحيحة بمشاكل عمل عن فشل النقل أو المحلل.
تسلسل الحقول الجذرية لا يخلق ذرية
تنفذ GraphQL حقول جذور الطفرة تسلسلياً. لا يلفها ذلك بمعاملة واحدة أو يتراجع عن نجاح سابق عند فشل تال أو يحول الحقول المتداخلة لكتابات متسلسلة. ضع التغيير المتماسك خلف طفرة واحدة ودع المجال يحدد حد المعاملة. إن أرسل النشر رسالة خارجية فراجع توصيلاً دائماً ومستهلكاً يقبل التكرار. لا تدع أثر المرة الواحدة لمجرد إرسال وثيقة واحدة.
اطلب نتيجة تسوي حالة العميل
يمكن للرد إرجاع السجل المحدث المعتمد ليصحح العميل التنسيق والافتراضات التي يضعها الخادم بدلاً من افتراض أن نصه هو المخزن. تمسح العملية summary بـnull صريحة وفق السياسة. إن أعاد التطبيق مشكلة تحقق يعرضها العميل دون ادعاء نجاح. أما فشل الشبكة فيحتاج سياسة نتيجة غير مؤكدة ولا يتحول دائماً لإعادة آمنة.
mutation ClearSummary($input: EditCourseInput!) {
editCourse(input: $input) {
course { id summary }
problems { field code }
}
}تطلب المتغيرات {"input":{"id":"c1","summary":null}} المسح. قد يعيد نجاح العينة summary بقيمة null وproblems فارغة.
صمم الرفض المتوقع كجزء من المجال
قد يكون طول عنوان مرفوض أو نسخة قديمة نتيجة عمل متوقعة تستفيد من رمز ثابت وإشارة حقل. تعالج أعطال المصدر غير المتوقعة كأخطاء تنفيذ مع ضبط الإفصاح. لا توجد قناة واحدة إلزامية لكل فعل مرفوض لكن يجب اتساق العقد. احفظ تفاصيل الاستثناء الداخلية، واختبر التفويض والتحقق دون كتابة والنجاح والتعارض والمهلة بعد الحفظ كل حالة مستقلة.
الأخطاء الشائعة وإصلاحها
يستخدم نوع إخراج كوسيط
- لماذا يحدث؟
- اختلطت فئات الإدخال والإخراج.
- كيف تصلحه؟
- عرف كائن إدخال مخصصاً بحقول مسموحة.
- كيف تتجنب تكراره؟
- تحقق من المخطط وراجع التعرض للتعيين الجماعي.
يفترض تراجع حقلَي طفرة معاً
- لماذا يحدث؟
- اختلط التسلسل بمعاملة مشتركة.
- كيف تصلحه؟
- عرف عملية مجال واحدة بحد معاملة صريح.
- كيف تتجنب تكراره؟
- اختبر الفشل بعد الأثر الأول.
يبقي الملخص الفارغ النص القديم
- لماذا يحدث؟
- استبدل كشف وجود العضو بفحص صدقه.
- كيف تصلحه؟
- ميز الحذف وnull والسلاسل المقدمة.
- كيف تتجنب تكراره؟
- احتفظ بعينات للحالات الثلاث.
اختبر فهمك
1. لماذا تعيد الطفرة الكائن المعتمد بدلاً من true فقط؟
اعرض الحل المشروح
يسمح بملاحظة قيم الخادم النهائية ومعرفاته ونسخته وتسوية المخبأ. يؤكد Boolean نتيجة محددة لكنه قليل الفائدة لتحديث العرض. أعد الحقول المسموحة ولا تتجاوز تفويض الإخراج لمجرد تحديث الكائن.
2. تنجح طفرة جذرية وتفشل التالية. ماذا لا يفترض العميل؟
اعرض الحل المشروح
لا يفترض تراجع التغيير الأول. يوفر التسلسل ترتيباً لا معاملة مشتركة أو تراجع آثار خارجية. افحص الحمولة ومسارات الخطأ وسو حالة الأولى بسياسة إعادة محددة. إن وجبت الذرية فأعد تصميم حد المجال.
أهم ما تعلمته
- تصف أنواع الإدخال البنية وتحدد قواعد المجال التغيير المسموح.
- لا يستبدل ترتيب الطفرة المعاملات أو قبول التكرار.