چگونه با GraphQL شروع کنیم

GraphQL ابزار انتخابی توسعه دهندگان برای توسعه API های کارآمد و قابل تکامل است. در اینجا اولین نگاهی به ابزارها و مفاهیمی است که به شما در شروع کار کمک می کند.

• زبان‌ها و چارچوب‌های GraphQL
• طرح جستجوی داده GraphQL
• ذخیره و بازیابی داده های GraphQL
• جستجوها و جهش های GraphQL
• ذخیره سازی GraphQL و شتاب عملکرد
• ابزارهای GraphQL

طراحی شده توسط Facebook و به عنوان یک استاندارد باز برای استفاده همه، GraphQL به عنوان جایگزینی برای REST APIs. مانند REST، GraphQL راهی برای ایجاد و مصرف API های مبتنی بر وب ارائه می دهد، اما پرس و جوها و داده های برگشتی از طرحواره های رسمی و یک سیستم نوع برای تضمین ثبات استفاده می کنند.

در این مقاله، اصول طراحی و پیاده‌سازی GraphQL API را بررسی می‌کنیم و در مورد بسیاری از ملاحظات و تصمیم‌های کلیدی که در طول این فرآیند می‌گیرید بحث خواهیم کرد.

زبان‌ها و چارچوب‌های GraphQL

اگر قصد دارید از GraphQL به‌عنوان API برنامه وب خود استفاده کنید، احتمال بسیار خوبی وجود دارد که زبان و اجزای داده‌ای که قبلاً استفاده می‌کنید از تلاش‌های شما پشتیبانی کند. کتابخانه‌های GraphQL تقریباً برای همه زبان‌های اصلی در تولید در دسترس هستند. کلاینت‌ها برای C#/.NET، Go، Java و Android، JavaScript، Swift/Objective-C، و Python در دسترس هستند و کتابخانه‌های سرور زمین‌های بیشتری را پوشش می‌دهند. 

اگر به‌طور کامل را از ابتدا شروع می‌کنید، بهتر است هر زبان، زمان اجرا و لایه داده‌ای را که بیشتر با آن‌ها آشنا هستید از پروژه‌های دیگر انتخاب کنید. استفاده از GraphQL محدودیت‌های زیادی را بر روی سرور یا کلاینت اعمال نمی‌کند و از نظر پایگاه‌داده ناشناس است. با این حال، ممکن است نیاز داشته باشید که بسته به آنچه که هست، کم و بیش یکپارچه سازی دستی لایه داده خود را انجام دهید. (اطلاعات بیشتر در مورد این در بخش بعدی.)

ما از پیاده‌سازی Python GraphQL برای مرجع در این مقاله استفاده خواهیم کرد. مفاهیم و عملکرد برای سایر زبان ها کم و بیش یکسان خواهد بود.

طرح جستجوی داده GraphQL

GraphQL پرس و جوهایی را می گیرد که از فیلدهای قوی تایپ شده در ترتیبات سلسله مراتبی مختلف ساخته شده اند. تنها بخشی از ایجاد یک GraphQL API که باید بیشتر به آن فکر کنید این است که چه طرحی را برای پرس و جو ارائه کنید.

در بسیاری از موارد، فیلدهای پرس و جو را می توان یک به یک به یک منبع داده زیربنایی نگاشت، تا تمام فیلدهای مربوطه در پایگاه داده (یا سایر منابع داده) را برای درخواست های شما نشان دهد. از آنجایی که پرس و جوهای GraphQL می توانند به طور قابل توجهی بازتر و متنوع تر از همتایان REST خود باشند، باید از ابتدا برنامه ریزی کنید که کدام فیلدها را می توان پرس و جو کرد و چگونه آنها به پایگاه داده شما نگاشت می شوند.

به عنوان مثال، اگر یک جدول پایگاه داده برای فیلم ها داشته باشیم، با فیلدهای title و year (به عنوان یک عدد صحیح)، می توانیم از یک پرس و جو GraphQL مانند این استفاده کنیم:

type Character {
    title: String!
    year: Int
}

! زیر String به این معنی است که یک فیلد مشخص اجباری است، بنابراین برای انجام این پرس و جو حداقل به یک عنوان نیاز داریم.

همچنین باید مطمئن شوید که فیلدهایی که از طریق GraphQL در معرض دید قرار می‌دهید، از انواعی استفاده می‌کنند که به درستی با داده‌های اصلی مطابقت دارند. به عنوان مثال، GraphQL نوع داده بومی «تاریخ» یا «تاریخ» ندارد، تا حد زیادی به دلیل تنوع بسیار زیاد پیاده‌سازی‌های موجود. اگر می‌خواهید جستجو بر اساس محدوده تاریخ را مجاز کنید، باید قالب‌بندی تاریخ‌ها را که از طریق API دریافت می‌شود، اعمال کنید، و همچنین اطمینان حاصل کنید که این درخواست‌های تاریخ به همتایان مناسب خود برای پایگاه داده پشتیبان ترجمه می‌شوند. .

بسته به چارچوبی که استفاده می‌کنید، ممکن است این کار قبلاً برای شما انجام شده باشد. گرافن، یک کتابخانه GraphQL محبوب برای Python، مقادیر تاریخ-زمان قالب‌بندی‌شده ISO-8601 را به‌عنوان یک نوع بومی ارائه می‌دهد، بنابراین نیازی نیست خودتان در مورد آن بحث کنید. p>

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

ذخیره و بازیابی داده های GraphQL

ذخیره سازی و بازیابی داده ها از قسمت پشتی شما معمولاً از میان افزار پشتیبانی شده توسط کتابخانه GraphQL برای زبان شما استفاده می کند.

در بسیاری از موارد، می‌توانید از GraphQL این کار را از طریق لایه‌های داده برای چارچوب‌های کاربردی رایج انجام دهید. برای مثال، کتابخانه Graphene Python برای GraphQL، از چارچوب وب جنگو به همراه ORM داخلی جنگو پشتیبانی می‌کند. Graphene همچنین از SQLAlchemy ORM پشتیبانی می‌کند و از چارچوب‌های محبوب Starlette و FastAPI پشتیبانی می‌کند. همچنین می‌تواند با رابط‌های داده Google App Engine و چارچوب Relay JavaScript (که توسط React استفاده می‌شود) تعامل داشته باشد.

اگر از یک لایه داده استفاده می‌کنید که با هیچ یک از این مؤلفه‌ها توصیف نشده است، می‌توانید از Graphene middleware و DataLoader اشیاء برای بستن شکاف اینها مکان هایی را در اختیار شما قرار می دهند تا به صورت دستی ادغام مورد نیاز خود را با لایه داده خود وصل کنید. با DataLoader، شما راهی برای ادغام چندین درخواست همزمان برای داده‌های مرتبط و در نتیجه کاهش تعداد رفت‌وآمدها به انتهای خود دارید.

هیچکدام از اینها، به هر حال، مانع از این نمی شود که خودتان در هیچ لایه ای از برنامه، خود را در حافظه پنهان انجام دهید. برای مثال، پاسخ‌هایی که برمی‌گردانید می‌توانند از طریق یک پروکسی در حافظه پنهان شوند، در حالی که داده‌های پشتیبان را می‌توان با استفاده از Memcached یا Redis در حافظه پنهان ذخیره کرد. با این اوصاف، این مسئولیت شماست که مطمئن شوید هر زمان که داده ها تغییر می کند، آن حافظه های پنهان خارج می شوند.

جستجوها و جهش های GraphQL

GraphQL از فرمت پرس و جوی خاصی به نام “پرس و جوی جهش” برای ایجاد، به روز رسانی یا حذف عناصر از مجموعه داده استفاده می کند. درباره نحوه کارکرد این پرسش‌ها کمی فکر کنید – نه فقط به کدام پرس‌وجوها اجازه می‌دهید و چه فیلدهایی برای آنها نیاز دارید، بلکه همچنین چه داده‌هایی را از پرس‌وجو پس از جهش برمی‌گردانید.

هنگامی که پرس و جوی جهش را طراحی می کنید، می توانید اجازه بازگشت هر تعداد فیلد خروجی را بدهید. با این اوصاف، احتمالاً ایده خوبی نیست که اشیاء پاسخ را در عمق بیش از یک یا دو لایه قرار دهید، زیرا تجزیه نتایج را دشوار می‌کند – هم هنگام نگاه کردن به خود جستجو و هم هنگام نوشتن کد برای مدیریت نتایج.

یک هشدار مهم دیگر این است که اجازه ندهید عادت های قدیمی طراحی REST API نحوه سازماندهی جستجوهای جهش شما را دیکته کنند. به عنوان مثال، به جای ایجاد پرس و جوهای جهش متعدد برای رسیدگی به انواع مختلف تغییرات در یک شی (الگوی مشترک REST) ​​می توانید آنها را در یک جستار جهش واحد ادغام کنید. یکی از راه‌های انجام این کار، استفاده از فیلدهای متمایز و غیراختیاری برای ثبت هر عملیات ممکن است، مطابق با “upvote/downvote” در این مثال.

یکی دیگر می تواند استفاده از یک فیلد مقدار به اضافه یک نوع enum برای توصیف رفتار مورد نظر با آن ارزش یک مزیت بزرگ برای enum این است که بدون ابهام است: می توانید از آن برای انعکاس دقیق مقصود استفاده کنید، بنابراین بسیار مستندسازی می شود. این احتمال وجود دارد که کتابخانه GraphQL زبان شما راهی برای استفاده از enum هایی ارائه دهد که با اجرای خود زبان از مفهوم سازگار است. برای مثال، شماره‌های GraphQL در Graphene for Python می‌توانند بسیار شبیه کلاس enum کتابخانه استاندارد پایتون.

ذخیره سازی GraphQL و شتاب عملکرد

در زیر همه اینها، یک پرس و جو GraphQL مانند هر پرس و جوی دیگر داده ها را نظرسنجی و بازیابی می کند. این بدان معناست که می‌توان آن را با بسیاری از روش‌های مشابهی که برای سرعت بخشیدن به درخواست‌های API استفاده می‌شود تسریع کرد:

• Caching: هر سرویسی که دارای پایگاه داده به عنوان پایانه پشتی باشد، یا داده ها را از قسمت جلویی برمی گرداند، می تواند از ذخیره سازی در هر دو طرف بهره مند شود. به خاطر داشته باشید که مسئولیت منقضی شدن این کش ها بر عهده شماست، بنابراین احتمالاً باید از قلاب های میان افزاری چارچوب GraphQL (مانند مواردی که در بالا برای Graphene توضیح داده شد) برای راه اندازی چنین مواردی استفاده کنید. توصیه می‌شود هر زمان که ممکن است از شناسه‌های منحصربه‌فرد استفاده کنید برای پشتیبانی از حافظه پنهان سمت سرویس گیرنده. 
• مکان‌نما و صفحه‌بندی: یک درخواست باید دارای حد بالایی پیش‌فرض برای تعداد رکوردهایی باشد که در آن واحد برمی‌گرداند تا هم کلاینت و هم سرور در معرض سیل قرار نگیرند. همچنین منطقی است که به مشتریان اجازه دهیم به صراحت حداکثر تعداد رکوردهایی را که باید بازگردانده شوند، و اینکه کدام “صفحه” از رکوردها را درخواست کنند، منطقی است. اسناد رسمی GraphQL نکات مفیدی در مورد نحوه ادغام استعاره های صفحه بندی در قالب درخواست GraphQL دارد. li>

ابزارهای GraphQL

علاوه بر کتابخانه‌های موجود برای زبان‌های مختلف، GraphQL دارای تعداد زیادی ابزار بومی و شخص ثالث است تا توسعه کلاینت‌ها، سرورها، طرح‌واره‌ها و لایه‌های پردازش پرس و جو را آسان‌تر کند:

• Apollo GraphQL منابع خود را به ایجاد ابزار منبع باز برای GraphQL اختصاص می دهد، از جمله کاربران GraphQL و GraphQL سرورها. همچنین GraphQL Tools را نگهداری می‌کند، مجموعه‌ای از ابزارهای کمکی برای تولید و تمسخر طرح‌واره‌های GraphQL و “دوخت” چندگانه APIها در یک API واحد – انجام ماموریت اعلام شده GraphQL برای ادغام چندین نقطه پایانی API و مدیریت پذیرتر کردن آنها.
• اگر به دنبال انتقال یک API تولید شده توسط Swagger موجود به GraphQL هستید، Swagger2GraphQL ابزار برای این کار ساخته شده است. همچنین امکان نگهداری جانبی از یک API قدیمی تولید شده توسط Swagger را فراهم می کند، بنابراین می توانید از هر دو استاندارد در طول دوره انتقال استفاده کنید.
• در نهایت، گروه GraphQL خود فیس‌بوک چند ابزار ارزشمند دارد. GraphiQL یک IDE درون مرورگر برای ایجاد جستارهای GraphQL است. می توان آن را به صورت داخلی یا به عنوان یک راه حل عمومی استفاده کرد. همچنین یک اجرای جاوا اسکریپت GraphQL، یک GraphQL-over-HTTP و مجموعه سرویس گیرنده و یک سرویس زبان GraphQL برای IDE ها.