Query ها در GraphQL

در جلسه قبل با graphql آشنا شدیم. در این جلسه قصد داریم تا با شیوه ی نوشتن query در graphql آشنا شویم. قبل از شروع، در نظر داشته باشید که برای درک بهتر مطالب از یکی از API های موجود در وب برای این مقاله استفاده شده است. شما می توانید برای دسترسی به این API از لینک زیر استفاده کنید:

https://rickandmortyapi.com/graphql

          همچنین برای دسترسی به مستندها این API می توانید به لینک زیر مراجعه کنید:

https://rickandmortyapi.com/documentation

نکته: دقت شود به دلیل تحریم توسط CDN استفاده شده در API بالا، این آدرس به صورت پیش فرض بر روی IP های ایران بسته است.

استفاده از مستندها:

همانطور که در جلسه قبل گفته شد، از آنجایی که GraphQL دارای سیستم schema and type است، می تواند مستندهای درباره آنچه در اختیار کلاینت می گذارد ارائه دهد. برای دسترسی به این مستندها در API بالا، می توانید از تب DOCS استفاده کنید. این تب در تصویر زیر مشخص شده است:

 Field ها:

در ساده ترین حالت یک کوئری، کلاینت درخواست فیلد های مورد نظر خود را می دهد. برای مثال کوئری زیر را در نظر بگیرید:

query {
  characters {
    results {
      name
    }
  }
}

در قطعه کد بالا، کلاینت از کوئری تعریف شده در سرور با نام characters استفاده کرده و در این کوئری، فیلد results را درخواست کرده است. نتیجه این درخواست، آرایه ای از نوع Character است. این نوع نیز دارای فیلدهای مختلفی است. تمامی کوئری ها، تایپ ها و فیلد ها در مستندها API آورده شده است (در عکس قبل می توانید کوئری به همراه فیلدها و نوع آن را مشاهده کنید). نتیجه ی کوئری بالا به صورت زیر خواهد بود:

{
  "data": {
    "characters": {
      "results": [
        {
          "name": "Rick Sanchez"
        },
        // more fields
      ]
    }
  }
}

همانطور که می بینید، نتیجه ی کوئری دقیقا مانند خود کوئری خواهد بود. این یک اصل در GraphQL است. با توجه به کوئری ها و فیلدهای تعریف شده می توان کوئری های مختلفی را ایجاد کرد. به طور مثال و برای تمرین بیشتر در کوئری بالا، علاوه بر name فیلد id را نیز اضافه کنید و نتیجه ی آن را مشاهده کنید.

Argument ها:

در مثال قبل نتیجه ی کوئری یک آرایه بود. اما اگر قصد دریافت یک داده ی خاص را توسط GraphQL داشته باشیم، می توان از آرگومان ها استفاده کرد. برای این کار کوئری زیر را در نظر بگیرید:

query {
  character(id: 1) {
    name
  }
}

اگر دقت کنید در این کوئری از آرگومانی با نام id استفاده کرده ایم. آرگومان بالا به ما این امکان را می دهد تا داده ای با id داده شده را دریافت کنیم. نتیجه کوئری بالا به صورت زیر خواهد بود:

{
  "data": {
    "character": {
      "name": "Rick Sanchez"
    }
  }
}

آرگومان ها بسته به کوئری تعریف شده می توانند اجباری یا اختیار باشند. به طور مثال در کوئری قسمت قبل آرگومان های اختیاری page را می توان استفاده کرد:

query {
  characters(page: 2) {
    results {
      name
    }
  }
}

که نتیجه این کوئری، آرایه ی دیگری خواهد بود (که صفحه دوم لیست character ها را نمایش می دهد):

{
  "data": {
    "characters": {
      "results": [
        {
          "name": "Aqua Morty"
        },
        // more fields
      ]
    }
  }
}

همچنین کوئری ها می توانند چند آرگومان را بپذیرند. برای استفاده از چند آرگومان در کوئری آن ها را توسط کاما (,) جدا می کنیم. ترتیب استفاده از آرگومان ها مهم نیست.

Alias ها:

اگر دقت کرده باشید، در کوئری های قبلی، از آنجایی که در نتیجه، کلید آن دقیقا برابر با نام کوئری است، نمی توان از یک کوئری یکسان چند بار استفاده کرد. برای درک بهتر مثال زیر را در نظر بگیرید:

query {
  character(id: 1) {
      id
      name
  }
  
  character(id: 2){
    id
    name
  }
}

کوئری بالا باعث ایجاد خطا خواهد شد. چرا که نمی توان از یک کوئری یکسان چند بار استفاده نمود. برای رفع این مشکل می توان از alias ها استفاده کرد و به هر یک از کوئری ها یک نام اختصاص داد. برای مثال کوئری زیر را در نظر بگیرید:

query {
  character1: character(id: 1) {
    id
    name
  }

  character2: character(id: 2) {
    id
    name
  }
}

در این کوئری از دو alias با نام های character1 و character2 استفاده شده است. نتیجه ی این کوئری به صورت زیر خواهد بود:

{
  "data": {
    "character1": {
      "id": "1",
      "name": "Rick Sanchez"
    },
    "character2": {
      "id": "2",
      "name": "Morty Smith"
    }
  }
}

تا به این لحظه نحوه نوشتن کوئری های ساده ذکر شد. در جلسه بعد به بررسی مفهوم Fragment ها و استفاده از آن ها برای جلوگیری از نوشته شدن کدهای تکراری و همچنین بررسی متغیرها در کوئری های GraphQL خواهیم پرداخت.

پایدار و سرزنده باشید.