GraphQL / الأساسي: عقود اللغة والرد / الدرس 6
الردود والأخطاء وأغلفة HTTP
فسر data وerrors معاً وافصل تنفيذ اللغة عن أعراف نقل HTTP المتطورة.
في هذه الصفحة
أهداف الدرس
- صنف فشل الطلب والحقل والشبكة من الأدلة.
- صمم سياسة عميل تعترف بالبيانات الجزئية ونتيجة الكتابة غير المؤكدة.
اقرأ عقد الرد كله
قد تتضمن النتيجة data وerrors وextensions اختيارية. يختلف خطأ الطلب المانع للتنفيذ عن خطأ الحقل الذي يصاحب بيانات جزئية. لا تستبدل errors كل نتائج العمل المتوقعة؛ فقد تمثل في حمولة ذات أنواع. يحفظ العميل البيانات المفيدة المسموحة عندما تسمح سياسة الشاشة ويبين مناطق الفشل. اعتبار نجاح HTTP نجاحاً كاملاً أو رمي كل البيانات الجزئية استراتيجيتان ناقصتان.
حدد فشل التنفيذ بمسار الرد
افترض أن course وtitle وsummary تقبل null وأن المحلل الأخير فشل والعنوان نجح. يشير path لموضع الرد بما فيه الاسم البديل إن استعمل. وتشير locations لمواضع الوثيقة لا صفوف قاعدة البيانات. الرسالة والرمز هنا سياسة تطبيق توضيحية. لا تعرض تتبع المكدس أو رسائل قاعدة البيانات أو الأسرار في الخطأ العام، واحفظ الدليل الداخلي بمعرف ربط مضبوط.
{
"data": {"course": {"title": "Graph foundations", "summary": null}},
"errors": [{"message": "Summary unavailable", "path": ["course", "summary"], "extensions": {"code": "SOURCE_UNAVAILABLE"}}]
}يبقى العنوان صالحاً وفق قبول null في العينة. ولو منع summary ذلك فقد يستبدل الأب.
حالة النقل طبقة دليل أخرى
مواصفة اللغة مستقلة عن النقل. تعرف إرشادات HTTP الأنواع والطرق والسلوك منفصلة، وتظل وثيقة GraphQL-over-HTTP مرجع مسودة. فضل application/graphql-response+json إن دعم واختبر سياسة الطرفين الفعلية. قد يرسل الاستعلام بـGET أو POST المدعومة، ولا تنفذ الطفرة عبر GET. قد ترفض المصادقة أو نوع المحتوى أو JSON المعيبة الطلب قبل التنفيذ، فيستقبل العميل جسم خطأ HTTP عادياً.
افصل جسم الطلب عن تشغيله
يحتوي الجسم وثيقة واسم عملية ومتغيرات، وهو عينة تسلسل فقط بلا عنوان خدمة أو اعتماد. يقرنه دمج HTTP بترويستي Content-Type وAccept مناسبتين وحدود جسم وسياسة مصادقة قبل التنفيذ. يكون تسجيل الاسم ومعرف وثيقة آمن أضبط من الجسم كله. صنف خطأ وكيل غير JSON كفشل نقل ولا تسم استثناء التحليل خطأ عمل.
{
"query": "query Card($id: ID!) { course(id: $id) { title } }",
"operationName": "Card",
"variables": {"id": "c1"}
}تختار JSON الصحيحة Card وتوفر id وتوضح الغلاف دون إرسال.
احفظ عدم اليقين بدلاً من اختراع فشل
إن انقطع الاتصال بعد إرسال طفرة فغياب الرد لا يثبت عدم حفظ التغيير. تحتاج إعادة القراءة وتسوية الكتابة وقبول التكرار سياسات مختلفة. وقد تكون للاستعلام آثار مكلفة إن خالف المحلل توقعات القراءة، فراجع التنفيذ لا الكلمة فقط. حدد متى يعرض الجزء الباقي أو يحدث أو يمنع قراراً حساساً، وسجل المرحلة والمسار دون قيم شخصية.
الأخطاء الشائعة وإصلاحها
تعد HTTP 200 نجاحاً كاملاً
- لماذا يحدث؟
- تجاهل العميل errors وحمولة المجال.
- كيف تصلحه؟
- قيم النقل ونتيجة GraphQL والعمل منفصلة.
- كيف تتجنب تكراره؟
- اختبر بيانات جزئية ورفضاً متوقعاً.
تسبب المهلة نشراً مكرراً
- لماذا يحدث؟
- فسر غياب الرد كغياب أثر محفوظ.
- كيف تصلحه؟
- سو النتيجة بهوية عملية ثابتة وفق عقد تكرار.
- كيف تتجنب تكراره؟
- اختبر المهلة بعد الحفظ.
تصبح صفحة HTML للوكيل خطأ مجال
- لماذا يحدث؟
- افترض العميل أن كل جسم JSON من GraphQL.
- كيف تصلحه؟
- افحص النوع وفشل النقل قبل فك النتيجة.
- كيف تتجنب تكراره؟
- غط فشل النقل غير JSON في اختبارات العميل.
اختبر فهمك
1. يفشل ملخص يقبل null وينجح العنوان. ماذا يفحص العميل قبل إخفاء البطاقة؟
اعرض الحل المشروح
افحص data ومسار errors وقبول null وسياسة الشاشة. قد يعرض العنوان مع حالة تعذر الملخص، أو يمنع سيراً حساساً حتى اكتمال القراءة. يعتمد القرار على صحة العرض لا قاعدة عامة.
2. لماذا يميز العميل JSON المعيبة عن خطأ المحلل؟
اعرض الحل المشروح
قد تمنع JSON المعيبة وجود طلب GraphQL أصلاً، بينما يحدث خطأ المحلل بعد بدء عملية صحيحة. يختلف التشخيص والتكرار ولا يملك بيانات جزئية ومسارات إلا الثاني. احفظ نوع المحتوى والحالة والمرحلة دون أجسام خاصة.
أهم ما تعلمته
- قد يجمع الرد بيانات مفيدة وأخطاء حقول.
- يحتاج فشل النقل والكتابة غير المؤكدة سياسة مستقلة.