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

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

GraphQL هي لغة استعلام وبيئة تشغيل لواجهات API، طورتها فيسبوك. في نظام Node.js، المكتبة الأساسية للعمل مع GraphQL هي الحزمة graphql. توفر جميع الأدوات اللازمة لإنشاء والتحقق من صحة وتنفيذ استعلامات GraphQL. هذه المكتبة هي الأساس لأطر العمل الشهيرة مثل Apollo Server و Express-GraphQL وغيرها.

ما هو GraphQL ولماذا هو مطلوب؟

على عكس REST API، حيث يعيد كل نقطة نهاية بنية بيانات ثابتة، يسمح GraphQL للعميل بطلب الحقول التي يحتاجها فقط. هذا يحل مشكلة over-fetching (الحصول على بيانات زائدة) و under-fetching (نقص البيانات). المزايا الرئيسية:

• مرونة الاستعلامات: يحدد العميل بنفسه البيانات التي يريد الحصول عليها.
• نقطة دخول واحدة: جميع الاستعلامات تذهب إلى نقطة نهاية واحدة (مثل /graphql).
• كتابة صارمة: يحدد مخطط GraphQL أنواع البيانات وعلاقاتها.
• الاستبطان: يمكن إنشاء الوثائق وأدوات الاختبار تلقائياً (GraphiQL).

تثبيت مكتبة GraphQL لـ Node.js

للبدء، قم بتثبيت الحزمة عبر npm أو yarn:

npm install graphql

ستحتاج أيضاً إلى خادم HTTP، مثل express، وبرنامج وسيط express-graphql (أو Apollo Server). لكن المكتبة نفسها graphql هي النواة.

إنشاء أول مخطط و resolver

المخطط هو وصف لأنواع البيانات والعمليات المتاحة (الاستعلامات، الطفرات). الـ resolvers هي دوال تنفذ المنطق الفعلي لجلب البيانات.

مثال على مخطط بسيط بنوع واحد User واستعلام user:

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

// نحدد المخططconst schema = buildSchema(`  type User {    id: ID!    name: String    email: String  }

  type Query {    user(id: ID!): User  }`);

// البيانات (في مشروع حقيقي - قاعدة بيانات)const users = [  { id: '1', name: 'إيفان', email: 'ivan@example.com' },  { id: '2', name: 'ماريا', email: 'maria@example.com' }];

// الـ resolversconst root = {  user: ({ id }) => users.find(user => user.id === id)};

// تنفيذ الاستعلامgraphql({  schema,  source: '{ user(id: "1") { name email } }',  rootValue: root}).then(response => {  console.log(JSON.stringify(response));  // {"data":{"user":{"name":"إيفان","email":"ivan@example.com"}}}});

أنواع البيانات في GraphQL

تدعم مكتبة graphql جميع الأنواع القياسية:

• String — سلسلة نصية؛
• Int — عدد صحيح؛
• Float — عدد عشري؛
• Boolean — قيمة منطقية؛
• ID — معرف فريد (يتم تسلسله كسلسلة نصية).

يمكنك أيضاً إنشاء أنواع كائنات مخصصة، تعدادات (enum)، قوائم ([Type]) وحقول غير فارغة (Type!).

الطفرات والاشتراكات

تُستخدم الطفرات لتعديل البيانات (مشابهة لـ POST/PUT/DELETE في REST). تسمح الاشتراكات بتلقي التحديثات في الوقت الفعلي عبر WebSocket.

مثال على طفرة لإضافة مستخدم:

const schema = buildSchema(`  type Mutation {    addUser(name: String!, email: String!): User  }`);

const root = {  addUser: ({ name, email }) => {    const newUser = { id: String(users.length + 1), name, email };    users.push(newUser);    return newUser;  }};

// تنفيذ الطفرةgraphql({  schema,  source: 'mutation { addUser(name: "بيتر", email: "petr@example.com") { id name } }',  rootValue: root}).then(console.