14 أكتوبر 2025·7 دقيقة
ما هو GraphQL؟ دليل واضح للواجهات البرمجية وجلب البيانات
تعرف على ما هو GraphQL، كيف تعمل الاستعلامات والطفرات والمخططات، ومتى تستخدمه بدلاً من REST—مع مزايا عملية وعيوب وأمثلة.
تعرف على ما هو GraphQL، كيف تعمل الاستعلامات والطفرات والمخططات، ومتى تستخدمه بدلاً من REST—مع مزايا عملية وعيوب وأمثلة.
GraphQL هو لغة استعلام وبيئة تشغيل للواجهات البرمجية. ببساطة: هو طريقة يطلب بها تطبيق (ويب، جوال، أو خدمة أخرى) بيانات من واجهة برمجية باستخدام طلب واضح ومنظم—ويعيد الخادم استجابة تطابق ذلك الطلب.
العديد من واجهات البرمجة تجبر العملاء على قبول ما تُعيده نقطة نهاية ثابتة. هذا يقود غالبًا إلى مشكلتين:
مع GraphQL، يمكن للعميل طلب الحقول التي يحتاجها بالضبط، لا أكثر ولا أقل. هذا مفيد بشكل خاص عندما تحتاج شاشات مختلفة (أو تطبيقات مختلفة) إلى "شرائح" مختلفة من نفس البيانات الأساسية.
عادةً ما يجلس GraphQL بين تطبيقات العميل ومصادر بياناتك. قد تكون تلك المصادر:
يتلقى خادم GraphQL استعلامًا، يحدد كيفية جلب كل حقل مطلوب من المكان المناسب، ثم يجمع الاستجابة النهائية بصيغة JSON.
فكر في GraphQL كأنك تطلب استجابة بشكل مخصص:
يُساء فهم GraphQL أحيانًا، فإليك بعض التوضيحات:
إذا حافظت على التعريف الأساسي—لغة استعلام + بيئة تشغيل للواجهات البرمجية—ستملك الأساس الصحيح لكل شيء آخر.
تم إنشاء GraphQL لحل مشكلة عملية في المنتج: كانت الفرق تقضي وقتًا طويلاً في جعل الواجهات البرمجية تناسب شاشات الواجهة الحقيقية.
تجبر واجهات برمجة التطبيقات التقليدية القائمة على النقاط النهائية غالبًا على الاختيار بين شحن بيانات لا تحتاجها أو إجراء مكالمات إضافية للحصول على ما تحتاجه. مع نمو المنتجات، يظهر ذلك كصفحات أبطأ، كود عميل أكثر تعقيدًا، وتنسيق مؤلم بين فرق الواجهة الأمامية والخلفية.
جلب بيانات أكثر من اللازم يحدث عندما تُعيد نقطة نهاية كائنًا "كاملًا" رغم أن شاشة ما تحتاج فقط إلى بعض الحقول. قد تحتاج شاشة ملف تعريف على الهاتف المحمول إلى اسم وصورة رمزية فقط، لكن الواجهة تعيد عناوين، تفضيلات، حقول تدقيق، وأكثر. هذا يهدر النطاق الترددي وقد يضر بتجربة المستخدم.
جلب بيانات أقل من اللازم هو العكس: لا توجد نقطة نهاية واحدة تحتوي على كل ما تحتاجه واجهة العرض، لذا يجب على العميل إجراء طلبات متعددة وتجميع النتائج. هذا يزيد الكمون ويزيد فرص الفشل الجزئي.
تستجيب العديد من واجهات REST للتغيير بإضافة نقاط نهاية جديدة أو إصدار نسخ (v1, v2, v3). قد تكون الإصدارات ضرورية، لكنها تولد عمل صيانة طويل المدى: العملاء القدامى يستمرون في استخدام النسخ القديمة، بينما تتراكم الميزات الجديدة في مكان آخر.
نهج GraphQL هو تطوير المخطط بإضافة حقول وأنواع مع مرور الوقت مع الحفاظ على الحقول الحالية مستقرة. هذا يقلل غالبًا من الضغط لإنشاء "إصدارات جديدة" لمجرد دعم احتياجات واجهة مستخدم جديدة.
نادراً ما يكون للمنتجات الحديثة مستهلك واحد فقط. الويب، iOS، أندرويد، وتكاملات الشركاء كلها تحتاج أشكال بيانات مختلفة.
صُمم GraphQL بحيث يمكن لكل عميل طلب الحقول التي يحتاجها بالضبط—دون أن تُنشئ الخلفية نقطة نهاية منفصلة لكل شاشة أو جهاز.
تُعرف واجهة GraphQL بواسطة المخطط. فكر فيه كالاتفاق بين الخادم وكل عميل: يذكر ما البيانات الموجودة، كيف ترتبط، وما يمكن طلبه أو تغييره. لا يخمن العملاء النقاط النهائية—بل يقرؤون المخطط ويطلبون حقولًا محددة.
يتألف المخطط من أنواع (مثل User أو Post) وحقول (مثل name أو title). يمكن للحقول الإشارة إلى أنواع أخرى، وهذه هي طريقة GraphQL في نمذجة العلاقات.
إليك مثالًا بسيطًا بلغة تعريف المخطط (SDL):
type User {
id: ID!
name: String!
posts: [Post!]!
}
type Post {
id: ID!
title: String!
body: String
author: User!
comments: [Comment!]!
}
type Comment {
id: ID!
text: String!
author: User!
post: Post!
}
لأن المخطط قوي الأنواع، يمكن لـ GraphQL التحقق من الطلب قبل تشغيله. إذا طلب العميل حقلًا غير موجود (مثال: Post.publishDate عندما لا يحتوي المخطط على هذا الحقل)، يمكن للخادم رفض الطلب أو تنفيذه جزئيًا مع أخطاء واضحة—بدون سلوك غامض "ربما يعمل".
صُممت المخططات لتنمو. عادةً يمكنك إضافة حقول جديدة (مثل User.bio) دون كسر العملاء الحاليين، لأن العملاء يتلقون فقط ما يطلبونه. حذف الحقول أو تغييرها أكثر حساسية، لذا غالبًا ما يشيّع الفرق إهمال الحقول أولًا ثم ترحيل العملاء تدريجيًا.
عادةً ما تُعرض واجهة GraphQL من خلال نقطة نهاية واحدة (على سبيل المثال، /graphql). بدلًا من وجود عدة عناوين لكل مورد (مثل /users, /users/123, /users/123/posts)، ترسل استعلامًا إلى مكان واحد وتصف البيانات بالضبط التي تريدها أن تُعاد.
الاستعلام هو في الأساس "قائمة تسوق" من الحقول. يمكنك طلب حقول بسيطة (مثل id و name) وكذلك البيانات المتداخلة (مثل منشورات مستخدم حديثة) في نفس الطلب—دون تنزيل حقول إضافية لا تحتاجها.
إليك مثالًا صغيرًا:
query GetUserWithPosts {
user(id: "123") {
id
name
posts(limit: 2) {
id
title
}
}
}
استجابات GraphQL متوقعة: JSON الذي تتلقاه يعكس بنية استعلامك. هذا يجعل العمل على الواجهة الأمامية أسهل، لأنك لا تحتاج لتخمين مكان البيانات أو تحليل صيغ استجابة مختلفة.
مخطط استجابة مبسط قد يبدو كالتالي:
{
"data": {
"user": {
"id": "123",
"name": "Sam",
"posts": [
{ "id": "p1", "title": "Hello GraphQL" },
{ "id": "p2", "title": "Queries in Practice" }
]
}
}
}
إذا لم تطلب حقلًا فلن يتم تضمينه. إذا طلبته، يمكنك توقع وجوده في الموضع المطابق—مما يجعل استعلامات GraphQL وسيلة أنيقة لجلب ما تحتاجه كل شاشة أو ميزة.
الاستعلامات للقراءة؛ أما الطفرات فهي كيفية تغيير البيانات في واجهة GraphQL—إنشاء، تحديث، أو حذف سجلات.
تتبع معظم الطفرات نفس النمط:
input) مثل الحقول المطلوب تحديثها.عادةً ما تعيد طفرات GraphQL البيانات عن قصد، بدلًا من مجرد "success: true". إعادة الكائن المحدث (أو على الأقل id والحقول الأساسية) يساعد الواجهة على:
تصميم شائع هو نوع "الحمولة" الذي يتضمن الكيان المحدث وأي أخطاء.
mutation UpdateEmail($input: UpdateUserEmailInput!) {
updateUserEmail(input: $input) {
user {
id
email
}
errors {
field
message
}
}
}
لواجهات API المدفوعة بالواجهة، قاعدة جيدة هي: أعد ما تحتاجه لعرض الحالة التالية (مثل user المحدث بالإضافة إلى أي errors). هذا يبقي العميل بسيطًا، ويجنب التخمين بما تغيّر، ويجعل فشل العملية أكثر سهولة في التعامل بأناقة.
يصف مخطط GraphQL ما يمكن طلبه. المحللات تصف كيفية الحصول عليه فعليًا. المحلل هو دالة مرتبطة بحقل محدد في مخططك. عندما يطلب العميل ذلك الحقل، يستدعي GraphQL المحلل لجلب أو حساب القيمة.
ينفذ GraphQL الاستعلام عن طريق المشي على الشكل المطلوب. لكل حقل، يجد المحلل المطابق ويشغّله. بعض المحللات تعيد خاصية من كائن موجود بالفعل في الذاكرة؛ وأخرى تستدعي قاعدة بيانات أو خدمة أو تجمع مصادر متعددة.
على سبيل المثال، إذا كان مخططك يحتوي على User.posts، فقد يستعلم محلل posts عن جدول posts بواسطة userId، أو يستدعي خدمة منشورات منفصلة.
المحللات هي الغراء بين المخطط وأنظمتك الحقيقية:
هذا الربط مرن: يمكنك تغيير تنفيذ الخلفية دون تغيير شكل استعلام العميل—طالما ظل المخطط متناسقًا.
لأن المحللات يمكن أن تعمل لكل حقل ولكل عنصر في قائمة، فمن السهل عن طريق الخطأ إطلاق العديد من الاستدعاءات الصغيرة (مثال: جلب المنشورات لمئة مستخدم مع 100 استعلام منفصل). يمكن أن يجعل نمط "N+1" الاستجابات بطيئة.
إصلاحات شائعة تتضمن التجميع والتخزين المؤقت (مثل جمع المعرفات وجلبها في استعلام واحد) وأن تكون متعمدًا بشأن الحقول المتداخلة التي تشجع العملاء على طلبها.
غالبًا ما يُنفَّذ التفويض في المحللات (أو في وسيط مشترك) لأن المحللات تعرف من يطلب وما البيانات التي يتم الوصول إليها. يحدث التحقق عادة على مستويين: GraphQL يتعامل تلقائيًا مع التحقق من النوع/الشكل، بينما تفرض المحللات قواعد الأعمال (مثل "فقط المديرون يمكنهم تعيين هذا الحقل").
أمر يفاجئ القادمين الجدد إلى GraphQL هو أن الطلب يمكن أن "ينجح" وفي الوقت نفسه يتضمن أخطاء. ذلك لأن GraphQL مُوجه للحقل: إذا تم حل بعض الحقول ولم يتم حل بعضها، قد تحصل على بيانات جزئية.
يمكن أن تحتوي استجابة GraphQL النموذجية على كلٍ من data ومصفوفة errors:
{
"data": {
"user": {
"id": "123",
"email": null
}
},
"errors": [
{
"message": "Not authorized to read email",
"path": ["user", "email"],
"extensions": { "code": "FORBIDDEN" }
}
]
}
هذا مفيد: يمكن للعميل عرض ما لديه (مثال: ملف المستخدم) مع التعامل مع الحقل المفقود.
data مساوية لـ null.اكتب رسائل خطأ للمستخدم النهائي، لا للتصحيح. تجنب كشف تتبعات الاستدعاءات (stack traces)، أسماء قواعد البيانات، أو معرّفات داخلية. نمط جيد هو:
messageextensions.code قابلة للقراءة آليًاretryable: true)سجّل الخطأ التفصيلي جانب الخادم مع معرف طلب حتى تستطيع التحقيق دون كشف البِنية الداخلية.
حدد "عقدة" أخطاء صغيرة يتشاركها تطبيق الويب والجوال: قيم extensions.code مشتركة (مثل UNAUTHENTICATED, FORBIDDEN, BAD_USER_INPUT)، متى تعرض إشعارًا عامًّا مقابل أخطاء ضمن الحقول، وكيف تتعامل مع البيانات الجزئية. الاتساق هنا يمنع كل عميل من اختراع قواعده الخاصة بالأخطاء.
الاشتراكات هي طريقة GraphQL لـ دفع البيانات إلى العملاء عند تغيرها، بدلاً من أن يطلب العميل مرارًا. عادةً ما تُسلم عبر اتصال دائم (أشهرها WebSockets)، حتى يتمكن الخادم من إرسال الأحداث لحظة حدوثها.
تشبه الاشتراكات الاستعلام كثيرًا، لكن النتيجة ليست استجابة واحدة. إنها تدفق من النتائج—كل منها يمثل حدثًا.
تقنيًا، يشترك العميل في موضوع (مثال: messageAdded في تطبيق دردشة). عندما ينشر الخادم حدثًا، يتلقى المشتركون المتصلون حمولة تطابق مجموعة الاختيار (selection set) للاشتراك.
تتألق الاشتراكات عندما يتوقع المستخدمون تغيّرًا فوريًا:
مع الاستطلاع يسأل العميل "هل هناك جديد؟" كل N ثانية. إنه بسيط لكنه قد يهدر الطلبات (خصوصًا عندما لا يتغير شيء) ويشعر بالتأخير.
مع الاشتراكات يقول الخادم "إليك التحديث" فورًا. هذا يمكن أن يقلل الحركة غير الضرورية ويحسّن الإحساس بالسرعة—على حساب الحفاظ على الاتصالات وإدارة بنية تحتية حيوية.
الاشتراكات ليست دائمًا جديرة بالجهد. إذا كانت التحديثات نادرة أو غير حساسة للزمن أو سهلة التجميع، غالبًا ما يكفي الاستطلاع أو إعادة الجلب بعد إجراءات المستخدم. كما أنها تضيف عبءًا تشغيليًا: توسيع الاتصالات، المصادقة على الجلسات طويلة العمر، إعادة المحاولات والمراقبة. قاعدة جيدة: استخدم الاشتراكات فقط عندما تكون اللحظية مطلبًا من متطلبات المنتج، لا لمجرد أن وجودها جيد أن يكون.
يُوصَف GraphQL غالبًا بأنه "قوة للعميل"، لكن تلك القوة لها تكاليف. معرفة المقايضات مقدمًا تساعدك في تحديد متى يكون GraphQL مناسبًا ومتى قد يكون مبالغًا فيه.
أكبر فائدة هي المرونة في جلب البيانات: يمكن للعملاء طلب الحقول التي يحتاجونها بالضبط، مما يقلل الجلب الزائد ويجعل تغييرات الواجهة أسرع.
ميزة كبيرة أخرى هي العقدة القوية التي يوفرها مخطط GraphQL. يصبح المخطط مصدر الحقيقة للأنواع والعمليات المتاحة، ما يحسن التعاون والأدوات.
غالبًا ما تشهد الفرق زيادة إنتاجية العميل لأن مطوري الواجهة الأمامية يمكنهم التكرار دون انتظار نسخ نقاط نهاية جديدة، وأدوات مثل Apollo Client يمكنها توليد الأنواع وتبسيط جلب البيانات.
قد يجعل GraphQL التخزين المؤقت أكثر تعقيدًا. مع REST، يكون التخزين غالبًا "على مستوى عنوان URL". مع GraphQL، يشارك كثير من الاستعلامات نفس النقطة النهاية، لذا يعتمد التخزين على أشكال الاستعلامات، الكاشات المنطقيّة، وتكوين دقيق على الخادم/العميل.
على جانب الخادم، هناك مزالق أداء. قد يؤدي استعلام صغير إلى العديد من الاستدعاءات الخلفية ما لم تصمم المحللات بعناية (التجميع، تجنّب نمط N+1، والتحكم في الحقول المكلفة).
هناك أيضًا منحنى تعلمي: المخططات، المحللات، وأنماط العميل قد تكون غير مألوفة للفرق المعتادة على واجهات مرتكزة على النقاط النهائية.
لأن العملاء يمكنهم طلب الكثير، يجب على واجهات GraphQL تطبيق حدود عمق وتعقيد الاستعلامات لمنع الطلبات الكبيرة المسيئة أو العرضية.
يجب تطبيق المصادقة والتفويض على مستوى الحقل، وليس فقط على مستوى المسار، لأن الحقول المختلفة قد تملك قواعد وصول مختلفة.
تشغيليًا، استثمر في التسجيل، التتبع، والمراقبة التي تفهم GraphQL: تتبُّع أسماء العمليات، المتغيرات (بحذر)، توقيتات المحللات، ومعدلات الأخطاء حتى تكتشف الاستعلامات البطيئة والانحدارات مبكرًا.
كل من GraphQL وREST يساعد التطبيقات على التحدث إلى الخوادم، لكن كل منهما ينظم تلك المحادثة بطرق مختلفة جدًا.
REST قائم على الموارد. تجلب البيانات عبر استدعاء نقاط نهاية تمثل "أشياء" مثل /users/123 أو /orders?userId=123. كل نقطة نهاية تعيد شكل بيانات ثابت يقرره الخادم.
يعتمد REST أيضًا على دلالات HTTP: طرق مثل GET/POST/PUT/DELETE، رموز الحالة، وقواعد التخزين. هذا قد يجعل REST طبيعيًا عندما تقوم بعمليات CRUD بسيطة أو تعمل مع مخابئ المتصفح/الوكيل.
GraphQL قائم على المخطط. بدلاً من نقاط نهاية عديدة، عادةً ما تملك نقطة نهاية واحدة، ويرسل العميل استعلامًا يصف الحقول التي يريدها. يتحقق الخادم من الطلب مقابل مخطط GraphQL ويعيد استجابة تطابق شكل الاستعلام.
هذَا "اختيار العميل للحقول" هو السبب في أن GraphQL يمكن أن يقلل من الجلب الزائد والجلب الناقص، خصوصًا لشاشات واجهة المستخدم التي تحتاج بيانات من عدة نماذج مرتبطة.
غالبًا ما يكون REST مناسبًا عندما:
تخلط العديد من الفرق بينهما:
السؤال العملي ليس "أي أفضل؟" بل "أي يناسب هذه الحالة مع أقل تعقيد؟"
تصميم واجهة GraphQL أسهل عندما تعاملها كمنتج لأولئك الذين يبنون الشاشات، لا كصورة مرآة لقاعدة بياناتك. ابدأ صغيرًا، تحقّق من حالات الاستخدام الحقيقية، وتوسع حسب الحاجة.
سجّل شاشاتك الأساسية (مثال: "قائمة المنتجات", "تفاصيل المنتج", "الدفع"). لكل شاشة، اكتب الحقول الدقيقة التي تحتاجها والتفاعلات التي تدعمها.
هذا يساعدك على تجنّب "الاستعلامات الإلهية (god queries)", يقلل الجلب الزائد، ويحدد مكان الحاجة للتصفية، الفرز، والصفحة.
عرّف أنواعك الأساسية أولًا (مثل User, Product, Order) وعلاقاتها. ثم أضف:
فضّل تسمية تُعبر بلغة الأعمال على تسمية قاعدة البيانات. "placeOrder" توضح النية أفضل من "createOrderRecord".
حافظ على تسمية متسقة: المفرد للعناصر (product)، الجمع للمجاميع (products). بالنسبة للترقيم الصفحات، عادةً ستختار أحدهما:
حتى على مستوى عالٍ، قرر مبكرًا لأنه يشكل بنية استجابة واجهتك البرمجية.
يدعم GraphQL أوصافًا مباشرة في المخطط—استخدمها للحقول، الوسائط، وحالات الحافة. ثم أضف أمثلة قابلة للنسخ في مستنداتك (بما في ذلك الترقيم الصفحي وسيناريوهات الأخطاء الشائعة). مخطط موصوف جيدًا يجعل الاستطلاع واستكشاف الواجهة البرمجية أكثر فائدة.
البدء مع GraphQL يتعلق في الغالب باختيار مجموعة أدوات مدعومة وإعداد سير عمل تثق به. لست مضطرًا لتبني كل شيء دفعة واحدة—اجعل استعلامًا واحدًا يعمل من النهاية إلى النهاية، ثم توسع.
اختر خادمًا بناءً على تكديسك البرمجي ومقدار "البطاريات المضمنة" التي تريدها:
خطوة عملية أولى: عرّف مخططًا صغيرًا (بضعة أنواع + استعلام واحد)، نفّذ المحللات، وربط مصدر بيانات حقيقي (حتى لو كان قائمة ثابتة في الذاكرة).
إذا أردت الانتقال أسرع من "فكرة" إلى واجهة عاملة، منصة برمجية مثل Koder.ai يمكن أن تساعدك في إنشاء تطبيق كامل صغير (React في الواجهة، Go + PostgreSQL في الخلفية) والتكرار على المخطط/المحللات عبر الدردشة—ثم تصدّر الكود المصدري عندما تكون مستعدًا لتملّك التنفيذ.
على الواجهة الأمامية، يعتمد اختيارك عادةً على ما إذا كنت تريد اتفاقيات محددة أو مرونة:
إذا كنت تنتقل من REST، ابدأ باستخدام GraphQL لشاشة أو ميزة واحدة، واحتفظ بـ REST للباقي حتى يثبت النهج جدارته.
عامل مخططك كعقدة للواجهة البرمجية. طبقات الاختبار المفيدة تتضمن:
لتعميق فهمك، تابع:
GraphQL هو لغة استعلام وبيئة تشغيل للواجهات البرمجية (APIs). يرسل العميل استعلامًا يصف الحقول التي يريدها بالضبط، ويعيد الخادم استجابة بصيغة JSON تعكس هذا الشكل.
من الأفضل تخيلها كطبقة بين العملاء ومصدر أو أكثر من مصادر البيانات (قواعد بيانات، خدمات REST، واجهات طرف ثالث، ميكروخدمات).
GraphQL يساعد بشكل أساسي في حل مشكلتين:
بإتاحة طلب الحقول المحددة فقط (بما في ذلك الحقول المتداخلة)، يمكن لـ GraphQL تقليل نقل البيانات غير الضروري وتبسيط كود العميل.
GraphQL ليس:
عاملها كعقد للواجهة البرمجية + محرك تنفيذ، وليس كحل لتخزين البيانات أو كخدعة أداء سحرية.
تعرض معظم واجهات GraphQL نقطة نهاية واحدة (غالبًا /graphql). بدلًا من عدة روابط URLs، ترسل عمليات مختلفة (استعلامات/طفرات) إلى تلك النقطة.
النتيجة العملية: عادةً ما تعتمد التخزين المؤقت والرصد أكثر على اسم العملية + المتغيرات بدلاً من عنوان URL.
المخطط (schema) هو عقد الواجهة البرمجية. يعرّف:
User, Post)User.name)User.posts)لأنه ، يمكن للخادم التحقق من الاستعلامات قبل تنفيذها وإرجاع أخطاء واضحة عندما تطلب الحقول غير الموجودة.
الاستعلامات في GraphQL هي عمليات قراءة. تحدد الحقول التي تحتاجها، وتطابق استجابة JSON بنية الاستعلام.
نصائح:
query GetUserWithPosts) لتحسين التصحيح والمراقبة.posts(limit: 2)).الطفرات (Mutations) هي عمليات كتابة (إنشاء/تحديث/حذف). النمط الشائع هو:
inputإرجاع البيانات (لا يقتصر على success: true) يساعد الواجهة على التحديث فورًا ويحافظ على اتساق الكاش.
المحللات (Resolvers) هي دوال على مستوى الحقل تخبر GraphQL كيفية جلب أو حساب كل حقل.
عمليًا، قد تقوم المحللات بـ:
غالبًا ما يُفرض التفويض (authorization) داخل المحللات أو عبر وسيط مشترك لأنها تعرف من يطلب أي بيانات.
من السهل توليد نمط N+1 (مثال: تحميل المنشورات لكل من 100 مستخدم على حدة).
التخفيف الشائع:
قِس توقيتات المحللات وابحث عن استدعاءات متكررة للأنظمة الخلفية خلال طلب واحد.
يمكن أن يعيد GraphQL بيانات جزئية مع مصفوفة errors. يحدث ذلك عندما تُحل بعض الحقول بنجاح وتفشل أخرى (مثل حقل محجوز أو انتهاء مهلة خدمة خلفية).
ممارسات جيدة:
extensions.code (مثل FORBIDDEN, BAD_USER_INPUT)يجب أن يقرر العميل متى يعرض البيانات الجزئية أو يتعامل مع العملية كفشل كامل.