پرش به محتوای اصلی

راهنمای قالب‌بندی و اعتبارسنجی GraphQL

زمان مطالعه: ۲ دقیقه

این ابزار چیست؟

GraphQL به کلاینت اجازه می‌دهد دقیقاً همان فیلدهایی را بخواهد که لازم دارد. کوئری‌هایی که در کد، گزارش شبکه یا مستندات می‌بینید اغلب فشرده یا نامرتب‌اند و پیش از فرستادن معلوم نیست با اسکیمای سرور جور درمی‌آیند یا نه. این ابزار کوئری یا اسکیما را قالب‌بندی یا فشرده می‌کند، کوئری را با SDL اسکیما اعتبارسنجی می‌کند و خطاها را با خط و ستون و توضیح فارسی نشان می‌دهد.

در بخش «عملیات‌ها» نام و نوع هر عملیات و فرگمنت را می‌بینید و در «SDL و Introspection» اسکیما را میان SDL و JSON حاصل از introspection تبدیل می‌کنید. همه‌چیز در مرورگر شما و با کتابخانه‌ی رسمی graphql-js انجام می‌شود.

گام‌به‌گام

  1. کار را انتخاب کنید

    «قالب‌بندی»، «فشرده‌سازی»، «اعتبارسنجی»، «عملیات‌ها» یا «SDL و Introspection» را بردارید.

  2. کوئری را بچسبانید

    کوئری، جهش یا اشتراک را بنویسید؛ نتیجه همان لحظه ساخته می‌شود.

  3. برای اعتبارسنجی اسکیما بدهید

    در حالت اعتبارسنجی، SDL اسکیما را در کادر دوم بگذارید تا فیلدهای ناموجود، آرگومان‌های جاافتاده و نوع‌های نادرست پیدا شوند.

  4. خروجی را بردارید

    کوئری مرتب یا فشرده را کپی کنید؛ در فشرده‌سازی، طول پیش و پس هم نمایش داده می‌شود.

نمونه‌های کاربردی

  • قالب‌بندی کوئری یک‌خطی

    کوئری بی‌نام به شکل کوتاه { … } نوشته می‌شود و هر فیلد در خط خودش می‌نشیند.

    query{user(id:1){name posts{title}}}

    نتیجه: { user(id: 1) { name posts { title } } }

  • فیلدی که در اسکیما نیست

    نوع User فقط name دارد و کوئری email هم خواسته است.

    { user(id: 1) { name email } }

    نتیجه: خط ۱، ستون ۲۲: فیلد «email» روی نوع «User» وجود ندارد.

اشتباه‌های رایج

  • اعتبارسنجی با اسکیمای قدیمی: اگر SDL به‌روز نباشد، خطاهای ساختگی می‌بینید یا خطای واقعی را نمی‌بینید. اسکیما را از همان سرور بگیرید.
  • قرار دادن مقدارها مستقیم در متن کوئری: برای ورودی کاربر از متغیرها مثل $id استفاده کنید؛ هم امن‌تر است و هم کش‌پذیرتر.
  • درخواست فیلدهای زیاد برای اطمینان: مزیت GraphQL همین است که فقط آنچه لازم است را بخواهید؛ فیلدهای اضافه پاسخ را سنگین و کند می‌کنند.
  • باز گذاشتن introspection روی سرور عمومی بدون فکر: نقشه‌ی کامل API را در اختیار همه می‌گذارد. اگر API عمومی نیست، آن را در محیط عملیاتی محدود کنید.

SDL و introspection

SDL زبان تعریف اسکیمای GraphQL است؛ متنی خوانا مثل type User { name: String } که نوع‌ها و فیلدها را توصیف می‌کند. introspection پرس‌وجوی ویژه‌ای است که سرور در پاسخش همین اطلاعات را به شکل JSON برمی‌گرداند.

ابزارهایی مثل GraphiQL و سازنده‌های کد معمولاً یکی از این دو شکل را می‌خواهند. با تبدیل میان آن‌ها می‌توانید اسکیمای گرفته‌شده از سرور را بخوانید یا در ابزار دیگری به کار ببرید.

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

کوئری من به جایی فرستاده می‌شود؟
خیر. همه‌ی کارها با کتابخانه‌ی رسمی graphql در مرورگر شما انجام می‌شود و هیچ درخواستی به سرور GraphQL یا سرور ما نمی‌رود.
قالب‌بندی با کامنت‌ها چه می‌کند؟
کامنت‌های # در خروجی قالب‌بندی و فشرده‌سازی حذف می‌شوند، چون در درخت نحوی GraphQL جایی ندارند. توضیح‌های رشته‌ای (description) در SDL حفظ می‌شوند.
چطور از سرور واقعی introspection بگیرم؟
نتیجه‌ی کوئری introspection استاندارد را به‌صورت JSON در بخش «SDL و Introspection» بچسبانید؛ هم ساختار {"data": {"__schema": …}} و هم خود __schema پذیرفته می‌شود.

ابزارهای مرتبط