استفاده از GraphQL در Node.js — راهنمای کامل و عملی

GraphQL به‌عنوان جایگزینی قدرتمند برای REST، کنترل دقیق‌تر روی داده‌ها، کاهش تعداد درخواست‌ها و مستندسازی خودکار را فراهم می‌کند. در این مقاله به صورت کاربردی و فنی یاد می‌گیریم چگونه GraphQL را در محیط Node.js پیاده‌سازی کنیم، مشکلات رایج را رفع کنیم و نکات بهینه‌سازی و امنیت را اعمال کنیم.

چرا GraphQL و چرا Node.js؟

• انعطاف‌پذیری در درخواست‌ها: کلاینت می‌تواند تنها فیلدهای مورد نیاز را بگیرد.
• یک نقطه‌ی تماس (single endpoint): سادگی در مدیریت شبکه و نسخه‌بندی.
• اکوسیستم غنی Node.js: کتابخانه‌هایی مثل Apollo Server، Express و DataLoader برای حل مشکلات عملکردی وجود دارند.

شروع سریع — یک سرور ساده با Apollo Server

const { ApolloServer, gql } = require('apollo-server');

const typeDefs = gql`
  type User {
    id: ID!
    name: String!
    email: String!
  }

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

const users = [
  { id: '1', name: 'Ali', email: 'ali@example.com' },
  { id: '2', name: 'Sara', email: 'sara@example.com' }
];

const resolvers = {
  Query: {
    users: () => users,
    user: (_, { id }) => users.find(u => u.id === id)
  }
};

const server = new ApolloServer({ typeDefs, resolvers });

server.listen().then(({ url }) => {
  console.log(`Server ready at ${url}`);
});

این کد یک سرور ساده Apollo را راه‌اندازی می‌کند. typeDefs اسکیمای GraphQL را تعریف می‌کند و resolvers نحوه‌ی پاسخ‌دهی به کوئری‌ها را مشخص می‌کند. این مثال برای توسعه و آشنایی سریع مناسب است، اما در پروژه‌های واقعی باید اتصال به دیتابیس و مدیریت خطا اضافه شود.

اتصال به دیتابیس (مثال با MongoDB و mongoose)

const mongoose = require('mongoose');
const UserModel = mongoose.model('User', new mongoose.Schema({
  name: String,
  email: String
}));

// resolver example
const resolvers = {
  Query: {
    users: async () => await UserModel.find(),
    user: async (_, { id }) => await UserModel.findById(id)
  }
};

در اینجا از mongoose برای مدل‌سازی استفاده شده است. توابع resolver به صورت async نوشته شده‌اند تا عملیات پایگاه‌داده را انجام دهند. اتصال اولیه به MongoDB باید قبل از start شدن سرور انجام شود (مثلاً با mongoose.connect).

مسئله N+1 و استفاده از DataLoader

یکی از مشکلات رایج در GraphQL زمانی است که یک فیلد تو در تو نیاز به بارگیری داده‌ها برای هر آیتم دارد (مثلاً بارگذاری پست‌ها برای هر کاربر). این باعث درخواست‌های مکرر به دیتابیس می‌شود (N+1).

// naive resolver leading to N+1
const resolvers = {
  Query: {
    users: async () => {
      const users = await UserModel.find();
      // for each user, fetch posts separately -> N+1 queries
      for (const u of users) {
        u.posts = await PostModel.find({ authorId: u.id });
      }
      return users;
    }
  }
};

کد بالا مشکل N+1 را نمایش می‌دهد: برای هر کاربر یک درخواست جداگانه به دیتابیس جهت گرفتن پست‌ها ارسال می‌شود که مقیاس‌پذیری را کاهش می‌دهد.

راه‌حل: DataLoader (مثال بهینه)

const DataLoader = require('dataloader');

function createLoaders() {
  return {
    postsByAuthor: new DataLoader(async (authorIds) => {
      const posts = await PostModel.find({ authorId: { $in: authorIds } });
      // group posts by authorId
      return authorIds.map(id => posts.filter(p => p.authorId.toString() === id.toString()));
    })
  };
}

// usage in resolvers
const resolvers = {
  Query: {
    users: async (_, __, { loaders }) => {
      const users = await UserModel.find();
      return users;
    }
  },
  User: {
    posts: (user, _, { loaders }) => loaders.postsByAuthor.load(user.id)
  }
};

در این نسخه از DataLoader استفاده کردیم تا با یک کوئری همه‌ی پست‌ها برای لیستی از شناسه‌ها را دریافت کنیم و سپس نتایج را برای هر شناسه دسته‌بندی کنیم. DataLoader درخواست‌ها را دسته‌ای (batch) و کش می‌کند تا از N+1 جلوگیری شود.

نمونه پیکربندی سرور با لودرها و اتصال دیتابیس

const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: () => {
    return { loaders: createLoaders() };
  }
});

mongoose.connect(MONGO_URL).then(() => server.listen({ port: 4000 }));

در context هر درخواست، instance جدیدی از loaders ساخته می‌شود. این کار باعث می‌شود کش و batching در طول یک درخواست حفظ شود اما بین درخواست‌ها مجزا بماند (مهم برای جلوگیری از نشت داده بین کاربران).

بهینه‌سازی، کش و امنیت

• Caching: استفاده از Apollo Cache، Redis یا HTTP cache برای کوئری‌های ثابت.
• Rate limiting و depth limiting: جلوگیری از کوئری‌های بسیار عمیق و یا درخواست‌های فراوان توسط حملات مصرفی.
• Validation و Authorization: استفاده از middleware یا directives برای کنترل دسترسی به فیلدها.
• Persisted Queries: ارسال شناسه کوئری به جای متن کامل برای کاهش استفاده‌ی پهنای‌باند و حملات تزریق.
• Monitoring: استفاده از Apollo Engine یا ابزارهای APM برای بررسی کارایی و خطاها.

نمونه محدود کردن عمق کوئری (مثال با graphql-depth-limit)

const depthLimit = require('graphql-depth-limit');

const server = new ApolloServer({
  typeDefs,
  resolvers,
  validationRules: [depthLimit(10)]
});

این قطعه از بسته graphql-depth-limit استفاده می‌کند تا از ارسال کوئری‌های خیلی عمیق جلوگیری کند. عدد 10 به‌عنوان مثال است و باید بسته به API و نیازها تنظیم شود.

پرسش‌های متداول و نکات عملی

• چه زمانی از GraphQL استفاده نکنیم؟ زمانی که ساده‌سازی، کشینگ سطح بالا یا عملیات CRUD ساده و محدود است و هزینه‌ی معرفی GraphQL توجیه‌پذیر نیست.
• چگونه versioning را مدیریت کنیم؟ با deprecation در اسکیمای GraphQL و اضافه کردن فیلدهای جدید به‌جای حذف ناگهانی.
• چگونگی لاگ و خطایابی؟ ثبت queryId، متادیتا و خطاها در یک سیستم لاگ مرکزی و فعال‌سازی tracing.

جدول مقایسه مختصر: GraphQL vs REST

جمع‌بندی و منابع پیشنهادی

GraphQL در Node.js ترکیبی قدرتمند برای ساخت APIهای منعطف و مقیاس‌پذیر است. با رعایت الگوهای مناسب (DataLoader برای N+1، کشینگ، محدودیت عمق، و مدیریت دسترسی) می‌توان از مزایای آن بهره برد و از مشکلات عملکردی جلوگیری کرد. منابع مفید برای مطالعه بیشتر: مستندات Apollo، مستندات GraphQL.org، و کتابخانه DataLoader.

در صورت نیاز می‌توانم نمونه پروژه کامل، فایل‌های پیکربندی یا الگوی معماری (folder structure, CI/CD) را بر اساس استک شما آماده کنم.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال