نکات کلیدی
- 01Queries، mutations، subscriptions و SDL schemas را با استفاده از parser graphql.js رسمی قالببندی میکند.
- 02Syntax را تأیید میکند و شماره خط و ستون دقیق برای خطاها را گزارش میکند — هیچ schema نیاز نیست.
- 03نظرات GraphQL (#) بر روی قالببندی کنار میگذارند؛ از رشتههای توضیح برای مستندسازی که میخواهید حفظ کنید استفاده کنید.
- 04کاملاً در مرورگر شما اجرا میشود — queries API داخلی و schemas اختصاصی محرمانه میماند.
چرا GraphQL Documents را قالببندی کنیم؟
GraphQL queries میتوانند سریع پیچیده شوند — nested fragments، inline variables، operation definitions متعدد و SDL type definitions با interfaces و directives. قالببندی مسلسل peer review را سریعتر میکند و سادهتر است تا braces بسته نشده یا argument mismatches را بر طریق نگاه کنید.
فرمتکننده از parser graphql.js reference استفاده میکند — parser یکسانی که GraphQL specification با آن شحن میدهد. این به معنی قالببندی canonical که در اینجا دریافت میکنید با آنچه Prettier's GraphQL plugin و بیشتر GraphQL tooling تولید میکند مطابقت دارد. هر چیزی که در اینجا parse شود بهدرستی Apollo، Relay و graphql-request میں parse شود.
نحوه قالببندی GraphQL Document
- 01
GraphQL خود را جا دهید
Query، mutation، subscription، fragment یا SDL schema definition را در پنل ورودی جا دهید.
- 02
بر روی Format کلیک کنید
Parser document را با تورفتگی canonical صادر میکند — تورفتگی دو فضا، یک field در هر خط، تراز argument مسلسل. نتیجه در پنل خروجی ظاهر میشود.
- 03
Selection validate کنید
بر روی Validate کلیک کنید تا confirm کنید document بدون خروجی قالببندیشده parse میشود. نتیجه تأیید یا فهرست خطاهای syntax با شماره خط و ستون است.
- 04
نتیجه را کپی کنید
بر روی Copy کلیک کنید تا document قالببندیشده را دریافت کنید. آن را در codebase، توضیح PR یا فایل مستند جا دهید.
برای Schemas و API Queries درونی امن
Parser graphql.js کاملاً در مرورگر شما اجرا میشود. هیچ متن عملیات یا تعریف schema برای هیچ سرور ارسال نمیشود. این آن را برای قالببندی queryهایی که نامهای field خصوصی یا سیستمهای type درونی ارجاع میدهند امن میکند که نمیخواهید به third-party tools عرضه کنید.
تأیید در اینجا فقط نحوی است — ابزار تأیید میکند که document یک document GraphQL معتبر است، اما آن را بررسی نمیکند که آیا field names در یک schema واقعی موجود هستند، آیا variables argument types را مطابقت میدهند یا آیا directives بهدرستی اعمال میشوند. Schema-aware validation target schema را در کنار document بار شود نیاز دارد.
سؤالات متداول GraphQL Formatter
آیا قالببندی GraphQL بر اساس schema تأیید میکند؟
نه — فقط validation syntax. بررسی آنکه fields و arguments موجود هستند target schema نیاز دارد. این ابزار تأیید میکند document یک document GraphQL معتبر است، بیشتر نه.
آیا نظرات در GraphQL من حفظ خواهند شد؟
نه. Lines که با # شروع میشوند توسط parser کنار میگذارند. از triple-quoted description strings برای مستندسازیای که باید قالببندی survive کند استفاده کنید.
کدام نسخه GraphQL spec پشتیبانی میشود؟
October 2021 specification، از جمله OneOf input objects و @specifiedBy directive.
آیا میتوانم SDL schema definitions را قالببندی کنم، نه فقط operation documents؟
بله. Type definitions، interface declarations، union types، enums، directives و descriptions همگی از طریق فرمتکننده بهدرستی round-trip میشوند.
آیا query یا schema هیچ جای دیگری آپلود میشود؟
نه. Parser graphql.js کاملاً در مرورگر شما اجرا میشود — هیچ چیزی دستگاه شما را ترک نمیکند.