GraphQL یک زبان کوئری برای APIهاست که توسط فیسبوک توسعه داده شده و جایگزینی مدرن و منعطف برای REST به‌شمار می‌ره.

GraphQL به شما این امکان رو می‌ده که دقیقاً مشخص کنید چه داده‌هایی می‌خواهید دریافت کنید.

به‌جای اینکه چندین endpoint مختلف (مثل /users, /users/1/posts) در REST داشته باشید، در GraphQL فقط یک endpoint دارید و همه چیز از طریق کوئری (query) مشخص می‌شه.

مزایای GraphQL نسبت به REST

ویژگیGraphQLREST
تعداد درخواست‌هامعمولاً یک درخواست کافیستچندین درخواست نیاز است
حجم داده‌هافقط داده‌هایی که درخواست می‌کنیممکنه داده‌های اضافی ارسال بشه
انعطاف‌پذیریخیلی بالاست (query, mutation, subscription)کمتر
مستندسازیخودکار (با ابزارهایی مثل GraphiQL)معمولاً دستی یا Swagger

کاربردهای GraphQL

توسعه API‌های پیشرفته و منعطف

مخصوصاً برای اپلیکیشن‌های موبایل یا فرانت‌اندهایی مثل React, Angular, Vue

ساخت کوئری‌های دقیق برای دریافت اطلاعات دلخواه

مثل: { user(id: 1) { name email posts { title createdAt } } }

پرفورمنس بهتر در ارتباط با API

کاهش تعداد درخواست‌های HTTP

ایده‌آل برای تیم‌های فرانت‌اند

چون دیگه نیاز نیست backend برای هر درخواست خاص endpoint جدید بسازه

ساختار اصلی در GraphQL

  • Query: گرفتن داده (مثل GET در REST)
  • Mutation: تغییر داده (مثل POST, PUT, DELETE)
  • Subscription: دریافت داده بلادرنگ (Real-time)

مثال ساده از Query در GraphQL

query {
  products {
    id
    name
    price
  }
}

خروجی ممکنه شبیه این باشه:

{
  "data": {
    "products": [
      { "id": "1", "name": "Laptop", "price": 1200 },
      { "id": "2", "name": "Phone", "price": 700 }
    ]
  }
}

یک مثال ساده از استفاده‌ی GraphQL در یک پروژه Next.js با استفاده از کتابخانه‌ی معروف Apollo Client :

ساختار پروژه:

فرض می‌کنیم یک API داریم که از GraphQL پشتیبانی می‌کنه و endpoint اون اینه:

https://countries.trevorblades.com/

و ما می‌خوایم اطلاعات کشورها (name, code) رو از اون بگیریم.

1. نصب پکیج‌ها

در ترمینال:

npm install @apollo/client graphql

2.ساخت Apollo Client

فایل: lib/apollo-client.js

// lib/apollo-client.js
import { ApolloClient, InMemoryCache } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://countries.trevorblades.com/', // GraphQL endpoint
  cache: new InMemoryCache(),
});

export default client;

3. استفاده در یک صفحه Next.js

فایل: pages/index.tsx (یا .js اگر با جاوااسکریپت کار می‌کنی)

// pages/index.tsx
import { gql } from '@apollo/client';
import client from '../lib/apollo-client';

export default function Home({ countries }: { countries: any[] }) {
  return (
    <div style={{ padding: 20 }}>
      <h1>Country List</h1>
      <ul>
        {countries.map((country: any) => (
          <li key={country.code}>
            {country.name} ({country.code})
          </li>
        ))}
      </ul>
    </div>
  );
}

export async function getStaticProps() {
  const { data } = await client.query({
    query: gql`
      query {
        countries {
          code
          name
        }
      }
    `,
  });

  return {
    props: {
      countries: data.countries,
    },
  };
}

چه اتفاقی افتاد؟

  • با Apollo Client یه درخواست به endpoint GraphQL زدیم
  • query نوشتیم تا name و code کشورهای مختلف رو بگیریم
  • از getStaticProps برای pre-render در Next.js استفاده کردیم
  • داده‌ها در صفحه نمایش داده شدن

نتیجه:

با این روش:

  • نیازی به REST API نداریم
  • فقط فیلدهایی که لازم داریم رو می‌گیریم
  • می‌تونیم راحت با قدرت GraphQL در صفحات Next.js کار کنیم