مختبِر استعلامات GraphQL

بمساعدة الخادم اختبار واجهات API

عميل GraphQL مركّز: اكتب الاستعلام، وزوّده بمتغيرات JSON وترويسات المصادقة، وشغّله، ثم افحص البيانات والأخطاء. يتضمن التحقق من صياغة الاستعلام وأدوات مساعدة للاستبطان (introspection).

الخصوصية: تتم المعالجة في متصفحك حيثما أمكن. تُمرَّر فحوصات الشبكة عبر خادم متقن ولا تُحفظ.

ما هو GraphQL؟

GraphQL لغة استعلام وبيئة تشغيل لواجهات API يحدد فيها العميل بدقة الحقول التي يريدها ويتلقى استجابة JSON على شكل الاستعلام، من نقطة نهاية واحدة. يعرّف مخطط بأنواع ما يمكن طلبه؛ الاستعلامات تقرأ والطفرات (mutations) تكتب، وتصل الأخطاء في مصفوفة errors إلى جانب البيانات لا كرموز حالة HTTP.

كيفية استخدام مختبِر استعلامات GraphQL

  1. أدخل عنوان URL لنقطة نهاية GraphQL.
  2. اكتب الاستعلام أو التعديل (mutation)؛ ثم اضغط «تحقق» (Validate) لفحص الصياغة والاطلاع على المتغيرات المعلنة.
  3. املأ المتغيرات ككائن JSON (واسم العملية إذا كان المستند يحتوي على عدة عمليات).
  4. أرسل وافحص ملخّص البيانات/الأخطاء، ثم العرض الشجري أو JSON الخام.

مزايا مختبِر استعلامات GraphQL

  • محرّر استعلامات مع تحقق من الصياغة (الأقواس والسلاسل النصية والأجزاء fragments والمتغيرات) ومنسّق
  • متغيرات JSON واسم العملية، تُرسل بطريقة POST (أو GET) مع الترويسات الصحيحة
  • استعلامات الاستبطان (introspection) والحقول الجذرية بنقرة واحدة
  • ملخّص الاستجابة: الحقول الجذرية وأحجام القوائم والحقول ذات القيمة null وأخطاء GraphQL مع مواقعها ومساراتها
  • الترويسات والمصادقة وإعدادات المُرحِّل/الوضع المباشر مشتركة مع منشئ الطلبات

مثال على مختبِر استعلامات GraphQL

استعلام واجهة GraphQL عامة

الإدخال:

query CountryInfo($code: ID!) {
  country(code: $code) { name capital currency }
}
Variables: { "code": "SA" }

النتيجة:

OK · 1 root field: country
{
  "data": { "country": { "name": "Saudi Arabia", "capital": "Riyadh", "currency": "SAR" } }
}

الأسئلة الشائعة حول مختبِر استعلامات GraphQL

ما الذي يكتشفه المدقّق؟

الأقواس المعقوفة والهلالية غير المتوازنة، والسلاسل النصية بعلامات اقتباس مفردة، ومجموعات التحديد المفقودة، والرموز غير المعروفة في المستوى الأعلى، والعمليات غير المسمّاة في المستندات متعددة العمليات، والأجزاء (fragments) غير المعرّفة أو غير المستخدمة، والمتغيرات غير المعلنة أو غير المستخدمة.

كيف تُرسل المتغيرات؟

يجب أن يكون محتوى مربع المتغيرات كائن JSON. يُرسل بوصفه الخاصية "variables" في جسم طلب POST (أو كمعامل استعلام عند اختيار GET).

هل يمكنني تشغيل الاستبطان؟

نعم — يحمّل زر استعلام الاستبطان استعلام IntrospectionQuery القياسي؛ ثم يعرض ملخّص الاستجابة عدد الأنواع والحقول الجذرية التي يكشفها المخطط.

هل أحتاج إلى ضبط Content-Type؟

لا. تُضاف Content-Type: application/json وAccept: application/json تلقائياً ما لم تتجاوزهما في تبويب الترويسات.

ملاحظات تقنية

المدقّق فاحص خفيف يعتمد على تقسيم النص إلى رموز (tokenizer) وليس محلّل GraphQL كاملاً: يتحقق من توازن الأقواس، وصياغة السلاسل النصية، وبنية العمليات والأجزاء، وإعلان المتغيرات واستخدامها، ويبلّغ عن مواضع السطر/العمود. أما التحقق الكامل من المخطط فيجري على الخادم.

المراجع

  • GraphQL SpecificationGraphQL Foundationلغة استعلام GraphQL ونظام أنواعها وقواعد التحقق ودلالات التنفيذ.
  • OWASP Cheat Sheet Series: GraphQLOWASP Foundationمخاطر GraphQL الخاصة: حدود عمق الاستعلام وتعقيده، والاستبطان في الإنتاج، والتفويض على مستوى الحقل.
  • RFC 9110: HTTP SemanticsIETF · 2022معاني أساليب HTTP وحقول الترويسات ورموز الحالة والتفاوض على المحتوى، بغضّ النظر عن إصدار البروتوكول.