كيفية بناء خادم GraphQL API باستخدام Apollo Server

هل تساءلت يومًا كيف تنشئ واجهة برمجة تطبيقات (API) قوية تتيح للعملاء طلب ما يحتاجونه بالضبط؟ هذا هو سحر GraphQL، ومع Apollo Server، أصبح بناء واحدة أبسط مما تتخيل! إذا مللت من نقاط نهاية REST الجامدة، فإن GraphQL يوفر المرونة، وApollo Server هو الأداة المثالية لتحقيق ذلك. في هذا البرنامج التعليمي التفاعلي، سنتناول إعداد خادم GraphQL باستخدام Apollo Server، بدءًا من تهيئة المشروع وحتى اختبار الاستعلامات (queries) والتعديلات (mutations). سواء كنت تستخدم JavaScript أو TypeScript، سيكون لديك خادم يعمل في وقت قصير. دعنا نتعمق ونبني شيئًا رائعًا باستخدام GraphQL وApollo Server!

لماذا تختار GraphQL و Apollo Server؟

قبل أن نبدأ العمل، دعنا نتحدث عن سبب كون GraphQL وApollo Server ثنائيًا ديناميكيًا. GraphQL، الذي طورته فيسبوك عام 2012 وتم فتحه كمصدر مفتوح عام 2015، هو لغة استعلام لواجهات برمجة التطبيقات تتيح للعملاء طلب بيانات محددة، مما يقلل من مشكلات جلب البيانات الزائدة أو الناقصة الشائعة في واجهات برمجة تطبيقات REST. بدلاً من نقاط نهاية متعددة، لديك نقطة نهاية ذكية واحدة تقدم استجابات مخصصة. إنه فعال ومرن ومثالي للتطبيقات الحديثة ذات احتياجات البيانات المعقدة.

يأتي Apollo Server، وهو خادم GraphQL مفتوح المصدر ومدعوم من المجتمع من Apollo GraphQL. إنه جاهز للإنتاج، ويدعم Node.js، ويتكامل بسلاسة مع قواعد البيانات مثل MongoDB أو PostgreSQL. بفضل ميزات مثل ربط المخططات (schema stitching)، والتخزين المؤقت (caching)، والاشتراكات في الوقت الفعلي (real-time subscriptions)، فإنه يمثل حلاً شاملاً لبناء واجهات برمجة تطبيقات قابلة للتطوير. بالإضافة إلى ذلك، فهو سهل الاستخدام للمبتدئين ولكنه قوي للمحترفين. مقارنة ببدائل مثل Express-GraphQL، يقدم Apollo Server مراقبة أداء أفضل وإعدادًا أسهل. إذا كنت تبني مدونة، أو موقعًا للتجارة الإلكترونية، أو واجهة خلفية لتطبيق جوال، فإن هذا المزيج سيوفر عليك الوقت والمتاعب. هل أنت متحمس؟ دعنا نعد مشروعنا!

إعداد مشروعك في JavaScript أو TypeScript

لنبدأ بإنشاء الأساس. سنقوم بإعداد مشروع Node.js وتثبيت الحزم الضرورية. يمكنك اختيار JavaScript للبساطة أو TypeScript لسلامة الأنواع — كلاهما يعمل بشكل رائع مع Apollo Server.

الخطوة 1: تهيئة المشروع

إنشاء مجلد جديد:

• افتح الطرفية (terminal) الخاصة بك وأنشئ دليل مشروع:

mkdir graphql-apollo-server
cd graphql-apollo-server

تهيئة Node.js:

• قم بتشغيل الأوامر التالية:

npm init -y
npm pkg set type="module"

• ينشئ هذا ملف package.json لإدارة التبعيات ويقوم بإعداد مشروع باستخدام وحدات ES.

الخطوة 2: تثبيت التبعيات

يتطلب Apollo Server حزمتين رئيسيتين: `@apollo/server` للخادم و`graphql` لمكتبة GraphQL الأساسية. بالنسبة لـ TypeScript، سنضيف الأنواع وخطوة بناء.

تثبيت التبعيات:

npm install @apollo/server graphql

بالنسبة لـ JavaScript:

ما عليك سوى استبدال إدخال scripts الافتراضي في ملف package.json الخاص بك بإدخالات type وscripts هذه:

{
	// ...etc.
	"type": "module",
    "scripts": {
    	"start": "node index.js"
    }
    // other dependencies
}

بالنسبة لـ TypeScript (موصى به):

1. تهيئة TypeScript:

npm install --save-dev typescript @types/node

• أنشئ ملف tsconfig.json في الدليل الجذر الخاص بك وقم بتحريره ليتضمن:

{
  "compilerOptions": {
    "rootDirs": ["src"],
    "outDir": "dist",
    "lib": ["es2023"],
    "target": "es2023",
    "module": "esnext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "types": ["node"]
  }
}

2. أخيرًا، استبدل إدخال scripts في ملف package.json الخاص بك بإدخالات type وscripts التالية:

{
	// ...etc.
    "type": "module",
    "scripts": {
    	"compile": "tsc",
    	"start": "npm run compile && node ./dist/index.js"
    }
	// other dependencies
}

نصيحة احترافية: إذا كنت جديدًا على TypeScript، فإنه يضيف أمانًا للأنواع إلى مخططك ومحللاتك (resolvers)، مما يساعد في اكتشاف الأخطاء مبكرًا. JavaScript أسرع للنماذج الأولية — اختر بناءً على حجم مشروعك.

الخطوة 3: إنشاء ملف الخادم

أنشئ مجلد src في جذر مشروعك وأضف ملف index.ts (أو index.js لـ JavaScript) في المجلد الجديد. هذا هو المكان الذي سنقوم فيه بتعريف المخطط (schema) والمحللات (resolvers).

اختبار استعلام بسيط

دعنا نبني أول استعلام لنا — رسالة "مرحبًا" بسيطة. هذا يقدم تعريفات أنواع GraphQL (المخطط) والمحللات (الدوال التي تجلب البيانات).

تعريف مخطط GraphQL

المخطط هو المخطط الأساسي لواجهة برمجة التطبيقات الخاصة بك. استخدم وسم gql من graphql-tag (المضمن مع `@apollo/server`) لتعريفه.

في index.ts (أو index.js):

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';


// Define GraphQL schema
const typeDefs = `
  type Query {
    hello: String
  }
`;

// Define resolvers
const resolvers = {
  Query: {
    hello: () => "Hello! Welcome to my server",
  },
};

// Create and start the server
const server = new ApolloServer({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});

console.log(`🚀  Server ready at: ${url}`);

بالنسبة لـ JavaScript، استورد الأنواع:

const { ApolloServer } from '@apollo/server';
const { startStandaloneServer } from '@apollo/server/standalone';

// Rest is the same

تشغيل الخادم

ابدأ تشغيل الخادم الخاص بك:

node index.js  # For JavaScript
npm start  # For TypeScript

زر http://localhost:4000 في متصفحك. سترى GraphQL Playground — بيئة تطوير متكاملة (IDE) قائمة على الويب لاختبار الاستعلامات.

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

في Playground، قم بتشغيل هذا الاستعلام في اللوحة اليسرى:

query {
  hello
}

انقر على "Execute" (تنفيذ). على اليمين، سترى:

{
  "data": {
    "hello": "Hello! Welcome to my server"
  }
}

نجاح! يوضح هذا الاستعلام البسيط أساسيات GraphQL: نوع Query مع حقل hello يعيد سلسلة نصية. المحللات (Resolvers) هي "العقول" التي توفر البيانات — في هذه الحالة، رسالة ثابتة. إنها نقطة انطلاق رائعة للتحقق من إعداداتك.

اختبار استعلام بنوع معقد

الآن، دعنا نضيف بعض التعقيد بنوع مخصص. سننشئ نوع Book واستعلامًا لجلب قائمة بالكتب. هذا يوضح كيف يتعامل GraphQL مع البيانات المهيكلة.

تحديث المخطط

عدّل typeDefs لتضمين نوع Book:

const typeDefs = gql`
  type Book {
    title: String
    author: String
  }

  type Query {
    books: [Book]
  }
`;

إضافة بيانات عينة

أسفل typeDefs أضف بيانات العينة التالية لنوع Book الجديد الخاص بنا:

// Sample data
const books = [
  {
    title: 'The Awakening',
    author: 'Kate Chopin',
  },
  {
    title: 'City of Glass',
    author: 'Paul Auster',
  },
];

تحديث المحللات

استبدل محتوى المحلل (resolver) بما يلي لنوع books:

const resolvers = {
  Query: {
    books: () => books
  }
};

أعد تشغيل الخادم وعد إلى Playground.

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

شغل:

query GetBooks {
  books {
    title
    author
  }
}

النتيجة:

{
  "data": {
    "books": [
      {
        "title": "The Awakening",
        "author": "Kate Chopin"
      },
      {
        "title": "City of Glass",
        "author": "Paul Auster"
      }
    ]
  }
}

رائع، أليس كذلك؟ يجلب هذا الاستعلام مصفوفة من كائنات Book. يتيح GraphQL للعملاء تحديد الحقول التي يريدونها بالضبط — لا أكثر ولا أقل. إذا حذفت author، فإنه يعيد العناوين فقط. هذه المرونة هي السبب في أن GraphQL يتفوق على REST للتطبيقات التي تعتمد على البيانات بكثرة.

اختبار تعديل لإضافة بيانات

الاستعلامات (Queries) للقراءة، لكن التعديلات (mutations) للكتابة. دعنا نضيف تعديلًا لإنشاء كتاب جديد، موضحين كيف يتعامل GraphQL مع إنشاء البيانات.

تحديث المخطط

أضف نوع Mutation:

const typeDefs = `
  type Book {
    title: String
    author: String
  }

  type Query {
    books: [Book]
  }

  type Mutation {
    createBook(title: String!, author: String!): Book
  }
`;

علامة ! تعني حقولًا مطلوبة.

تحديث المحللات

const resolvers = {
  Query: {
    books: () => books,
  },
  Mutation: {
    createBook: (_: any, { title, author }: { title: string; author: string }) => {
      const newBook = { title, author };
      books.push(newBook);
      return newBook;
    }
  }  
};

اختبار التعديل

في Playground، قم بتشغيل:

mutation CreateBook{
  createBook(title: "Harry Potter", author: "J.K Rowling") {
    author
    title
  }
}

النتيجة:

{
  "data": {
    "createBook": {
      "title": "Harry Potter",
      "author": "J.K Rowling"
    }
  }
}

للتأكيد، أعد تشغيل استعلام GetBooks:

query GetBooks {
  books {
    title
    author
  }
}

النتيجة:

{
  "data": {
    "books": [
      {
        "title": "The Awakening",
        "author": "Kate Chopin"
      },
      {
        "title": "City of Glass",
        "author": "Paul Auster"
      },
      {
        "title": "Harry Potter",
        "author": "J.K Rowling"
      }
    ]
  }
}

تمت إضافة الكتاب الجديد! تعيد التعديلات (Mutations) البيانات التي تم إنشاؤها، مما يتيح للعملاء الحصول على ملاحظات فورية. في بيئة الإنتاج، اتصل بقاعدة بيانات مثل MongoDB للمثابرة.

JavaScript مقابل TypeScript: أيهما تختار؟ بالنسبة للنماذج الأولية السريعة، JavaScript جيد — قوالب أقل. ولكن للمشاريع الكبيرة، يتألق TypeScript بسلامة الأنواع للمخططات والمحللات. يكتشف TS الأخطاء مبكرًا، مما يجعل خادم GraphQL الخاص بك أكثر قوة.

إضافة المزيد من التعقيد: المعرفات (IDs) والاستعلامات مع الوسائط (Arguments)

لجعل الأمر واقعيًا، أضف معرفات (IDs) للكتب واستعلامًا لجلبها حسب العنوان.

تحديث المخطط:

const typeDefs = `
    type Book {
      id: ID!
      title: String
      author: String
    }

    type Query {
      books: [Book]
      book(title: String!): Book
    }

    type Mutation {
      createBook(title: String!, author: String!): Book
    }
`;

تحديث البيانات والمحللات:

// Sample data
const books = [
  {
    id: 1,
    title: 'The Awakening',
    author: 'Kate Chopin',
  },
  {
    id: 2,
    title: 'City of Glass',
    author: 'Paul Auster',
  },
];

// Resolvers 
const resolvers = {
  Query: {
    books: () => books,
    book: (_: any, { title }: { title: string }) => books.find(book => book.title === title),
  },
  Mutation: {
    createBook: (_: any, { title, author }: { title: string; author: string }) => {
      const newBook = { id: books.length + 1, title, author };
      books.push(newBook);
      return newBook;
    }
  }  
};

اختبار الاستعلام:

query GetBook {
  book(title: "The Awakening") {
    id
    title
    author
  }
}

النتيجة:

{
  "data": {
    "book": {
      "id": "1",
      "title": "The Awakening",
      "author": "Kate Chopin"
    }
  }
}

يوضح هذا الوسائط (arguments) في الاستعلامات، مما يتيح للعملاء تصفية البيانات بكفاءة.

أفضل الممارسات لـ GraphQL مع Apollo Server

• تصميم المخطط: اجعله معياريًا باستخدام ملفات متعددة.
• معالجة الأخطاء: استخدم ApolloError للأخطاء المخصصة.
• الأداء: قم بتمكين التخزين المؤقت باستخدام `@apollo/cache-control`.
• الاشتراكات: أضف الوقت الفعلي باستخدام `apollo-server-express`.
• المراقبة: استخدم Apollo Studio للمقاييس.

استكشاف المشكلات الشائعة وإصلاحها

• الخادم لا يعمل؟ تحقق من إصدار Node (14+) والتبعيات.
• أخطاء في الاستعلام؟ تحقق من مطابقة المخطط/المحلل.
• مشاكل CORS؟ أضف `{ cors: { origin: '*' } }` إلى خيارات الخادم.
• أخطاء TS؟ قم بتثبيت `@types/graphql` و`@types/node`.

الخاتمة

لقد قمنا ببناء خادم GraphQL قوي باستخدام Apollo Server، بدءًا من استعلامات الترحيب وحتى التعديلات. سواء كنت تستخدم JS أو TS، فأنت جاهز لإنشاء واجهات برمجة تطبيقات مرنة. قم بالتجربة، أضف الاشتراكات، وانشر على Heroku. GraphQL وApollo Server هما تذكرتك إلى واجهات برمجة تطبيقات فعالة!

يدعم Apidog أيضًا الاختبار باستخدام GraphQL، لذا تأكد من تجربته مجانًا تمامًا!