GraphQL.js لجافا سكريبت (Node.js): الدليل الشامل

1. ما هي هذه المكتبة ولماذا تحتاجها؟

GraphQL.js هي التطبيق المرجعي لمواصفات GraphQL بلغة JavaScript. توفر مجموعة كاملة من الأدوات لإنشاء وتنفيذ والتحقق من صحة استعلامات GraphQL على جانب الخادم (Node.js) وفي المتصفح. على عكس REST API، حيث يعيد كل نقطة نهاية بنية بيانات ثابتة، يتيح GraphQL للعميل طلب البيانات التي يحتاجها بالضبط دون أي زيادة. هذا يحل مشكلة جلب البيانات الزائدة (over-fetching) ونقص البيانات (under-fetching)، وهو أمر بالغ الأهمية لأداء تطبيقات الجوال وواجهات الويب المعقدة.

مكتبة GraphQL.js هي الأساس لجميع أطر عمل GraphQL الشهيرة في نظام JavaScript البيئي، مثل Apollo Server وExpress-GraphQL وYoga وغيرها. تتولى المهام الثقيلة مثل تحليل الاستعلامات والتحقق من صحتها وتنفيذ الدوال الحلالة (resolvers) وتشكيل الرد وفقًا للمواصفات بدقة. باستخدام GraphQL.js مباشرة، تحصل على أقصى تحكم في عملية معالجة الاستعلامات، وهو أمر مهم بشكل خاص عند إنشاء middleware مخصصة أو أدوات اختبار أو التكامل مع مصادر بيانات غير تقليدية.

تشمل المزايا الرئيسية لاستخدام GraphQL.js: الكتابة الصارمة للمخطط (schema)، التوليد التلقائي للتوثيق (عبر Introspection Query)، القدرة على دمج البيانات من مصادر متعددة (قواعد البيانات، REST API، الخدمات المصغرة) في استعلام واحد، بالإضافة إلى آليات مدمجة لمعالجة الأخطاء والترقيم (pagination). هذا يجعل المكتبة لا غنى عنها لبناء واجهات API حديثة وقابلة للتوسع ومرنة.

2. التثبيت

يتم تثبيت المكتبة عبر مدير الحزم npm (Node Package Manager). تأكد من تثبيت Node.js الإصدار 12 أو أعلى.

npm install graphql

للاستخدام في مشروع يدعم وحدات ES (type: "module" في package.json)، قم باستيراد الدوال كالتالي:

import { graphql, buildSchema } from 'graphql';

لـ CommonJS (الطريقة القياسية في Node.js):

const { graphql, buildSchema } = require('graphql');

3. البداية السريعة — مثال عملي بسيط

فيما يلي خادم بسيط يستقبل استعلام GraphQL ويعيد تحية. يوضح هذا المثال جوهر المكتبة: تعريف المخطط، الدوال الحلالة (resolvers)، وتنفيذ الاستعلام.

const { graphql, buildSchema } = require('graphql');

// 1. تعريف المخطط (Schema Definition Language - SDL)
const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

// 2. تعريف الدالة الحلالة الجذرية (root resolver)
const rootValue = {
  hello: () => {
    return 'مرحبًا، GraphQL.js!';
  },
};

// 3. تنفيذ الاستعلام
const query = '{ hello }';

graphql({
  schema,
  source: query,
  rootValue,
}).then((response) => {
  console.log(JSON.stringify(response, null, 2));
  // الإخراج: { "data": { "hello": "مرحبًا، GraphQL.js!" } }
});

4. أهم الدوال/الوظائف/الفئات

4.1. `buildSchema(schemaString: string): GraphQLSchema`

الوظيفة: تحليل سلسلة نصية مكتوبة بلغة مخططات GraphQL (SDL) وإنشاء كائن GraphQLSchema. هذه هي أسرع طريقة لتعريف المخطط دون استخدام المنشئ البرمجي.

const { buildSchema } = require('graphql');

const schema = buildSchema(`
  type Query {
    user(id: ID!): User
  }
  type User {
    id: ID
    name: String
  }
`);