این مقاله در ابتدا در وبلاگ شخصی Dev من ظاهر شد: Byte High ، بدون محدودیت.
GraphQL یک پرس و جو و زبان دستکاری API است. در سال 2012 توسط فیس بوک ایجاد شد ، در سال 2015 با منبع باز بود. در سال 2018 به بنیاد GraphQL منتقل شد و یک زبان تعریف طرحواره (SDL) را معرفی کرد. به نظر می رسد جایگزین استراحت به عنوان روش استاندارد برای افشای API های عمومی است. با استراحت ، باید ورودی ها و خروجی ها را برای هر نقطه پایانی تعریف کنید. در حالی که با GraphQL ، فقط یک نقطه پایانی وجود دارد و شما یک طرح را تعریف می کنید. کاربر فقط داده های لازم را برای به دست آوردن آنچه می خواهد ارسال می کند. و برخلاف SQL ، شما به یک منبع داده واحد محدود نمی شوید.
امسال مجبور شدم با GraphQL به سرعت سرعت بیشتری پیدا کنم. من فکر کردم که از هیچ چیز شروع نمی کنم ، اما فراموش کرده ام که Tinacms (سیستم مدیریت محتوای بی سر که من با این سایت استفاده می کنم) از آن استفاده می کند. یکی از اولین مشکلاتی که من برای حل آن باید حل کنم نحوه تولید مستندات استاتیک بود. تحقیقات محدود من مرا به دو راه حل ممکن سوق داد: SPECTAQL ، که از Dociql قبلی و Magidoc تهیه شده است. مورد دوم دارای جستجوی داخلی است ، به همین دلیل انتخاب من را برای من رقم زد. من از هوگو به عنوان ژنراتور سایت استاتیک خود استفاده می کنم ، بنابراین اولین کاری که باید انجام دهم این بود که نسخه محلی Tinacms را از مخزن GIT سایت خود شروع کنم:
npx tinacms dev - c "hugo server -D -p 1313"
با اجرای سرور محلی ، می توانید به http: // localhost: 1313/admin/#/graphql دسترسی پیدا کنید. GraphiQL اجرای مرجع زمین بازی GraphQL API است. اگر برای شما خیلی اساسی است ، یک جایگزین تجاری به نام آپولو وجود دارد. اجرای tinacms سه گزینه را به شما می دهد (از نمادهای سمت چپ انتخاب شده است):
- اسناد: اسناد API در یک ساختار درخت.
- تاریخ: پرس و جوهای قبلی.
- نمایش داده شد: سازنده پرس و جو.
بعد از اینکه نگاهی به بخش Docs در GraphQL انداختید ، خواهید فهمید که چرا می خواستم یک سایت استاتیک ایجاد کنم. با Magidoc آسان است. من این پرونده پیکربندی را به مخزن Git خود اضافه کردم:
export default {
introspection: {
type: 'url',
url: 'http://localhost:4001/graphql',
},
website: {
template: 'carbon-multi-page',
customStyles: ['/static/css/custom.css'],
},
}
سپس برای تولید اسناد ، وارد کنید: pnpm add --global @magidoc/cli\@latest && magidoc generate (شما به PNPM نصب شده نیاز دارید). به طور پیش فرض ، این یک سایت استاتیک در پوشه ای به نام Docs ایجاد می کند. با این حال ، شما فقط نمی توانید پرونده index.html را باز کنید. شما باید سرور را با آن راه اندازی کنید magidoc preview و سپس پیوند را دنبال کنید. ممکن است بخواهید پوشه Docs را به خود اضافه کنید .gitignore پرونده اما در تولید ، می توانید با استفاده از هر سرور وب مستقر شوید. خروجی مبتنی بر سیستم طراحی کربن IBM است.
اکنون برخی از مستندات قابل جستجو استاتیک را دریافت کرده اید ، می توانید به بررسی طرحواره خود بپردازید. Schema GraphQL را می توان به هر زبان برنامه نویسی که سیستم نوع را پیاده سازی می کند ، نوشته شود. با tinacms که به معنای TypeScript یا JavaScript است. در اینجا یک قطعه از تینا من است config.js پرونده:
طرحواره: {
مجموعه ها: [
{
name: "blog",
format: "md",
label: "Blog",
path: "content/blog",
defaultItem: () => {
return {
draft: true,
}
},
fields: [
{
name: "draft",
type: "boolean",
label: "Draft",
required: true,
},
{
name: "title",
type: "string",
label: "Title",
isTitle: true,
required: true,
},
{
name: "date",
type: "datetime",
label: "Date",
},
{
name: "description",
type: "string",
label: "Description",
},
{
name: "image",
type: "image",
label: "Image",
},
{
name: "image_license",
type: "string",
label: "Image License",
},
{
name: 'tags',
type: 'string',
label: 'Tags',
list: true,
},
{
name: 'body',
type: 'rich-text',
isBody: true,
label: "Body",
templates: [
{
name: 'shortcode',
label: 'shortcode',
This creates a schema type called Blog with the fields:
-
draft:
Boolean! -
title:
String! -
date:
String -
description:
String -
image:
String -
image_license:
String -
tags:
[String] -
بدنه:
JSON -
شناسه:
ID! -
_sys:
SystemInfo! -
_ مقادیر:
JSON!
زمینه ها می توانند مقیاس پذیر باشند (Booleanبا Floatبا Integerبا String و غیره) یا پیچیده (حاوی داده های دیگر). یک علامت تعجب آور ( ! ) به این معنی است که این زمینه مورد نیاز است (غیر قابل کنترل). براکت های مربع به معنای یک آرایه است. اگر نوع باشد JSON، سپس مجموعه ای از میدان های فرعی تعریف شده است. همچنین می توانید از انواع تعریف شده قبلاً برای ایجاد روابط استفاده کنید. به عنوان مثال ، اگر وبلاگ شما دارای چندین مشارکت کننده است ، می توانید زمینه ای به نام داشته باشید author با نوع User!بشر
نمایش داده شد
از آنجا که فقط یک نقطه پایانی وجود دارد ، باید آنچه را که می خواهید بگویید. به عنوان مثال ، برای به دست آوردن لیست مجموعه هایی که استفاده می کنید:
{
collections {
name
}
}
در collections ثبت شده است میدان اصلیبشر هر چیز دیگری است باربشر زیرا بار بار فقط حاوی است name پرس و جو لیستی از همه را برمی گرداند collections:
{
"data": {
"collections": [
{"name": "blog"},
{"name": "recipe"}
]
}
}
شما دقیقاً میزان اطلاعاتی را که در آن درخواست می کنید دریافت می کنید. همچنین می توانید استدلال ها را تصویب کنید. به عنوان مثال ، اگر می خواستید titleبا date وت draft وضعیت این مقاله که می توانید استفاده کنید:
{
blog(relativePath: "getting-started-with-graphql.md") {
title
date
draft
}
}
با این حال ، به طور معمول از یک متغیر در پرس و جو استفاده می کنید ، مانند این:
query blog($relativePath: String!) {
blog(relativePath: $relativePath) {
title
date
draft
}
}
متغیرها دارای پیشوند هستند ( دلار ). نوع (String در این مثال) در پرس و جو تعریف شده است. متغیر در blog پارامترها
جهش
پرس و جو معادل آن است GET در استراحت یا read در اصطلاحات سنتی داده ها. برای createبا update وت delete وجود دارد mutationبشر نحو همان است که برای نمایش داده شد. شاید متوجه شده باشید ID زودتر نوع. اگر هنگام ایجاد یک رکورد آن را مشخص کنید ، سرور GraphQL به آن یک شناسه منحصر به فرد می دهد. می توانید این مثال را از Documenation Tinacms (چسبیدن به منابع ناپلئون دینامیت) امتحان کنید:
mutation {
updatePost(relativePath: "voteForPedro.json", params: {title: "Vote For Napolean Instead", category: "politics", author: "content/authors/napolean.json"}) {
title
category
author {
... on Author {
id
}
}
}
}
اشتراک
من قبلاً در مورد معماری های رویداد محور نوشتم. اشتراک ها راهی برای دریافت داده ها از سرور GraphQL هر بار که یک رویداد مشترک برگزار می شود. همه سرورهای GraphQL برای پشتیبانی از اشتراک های WebSocket پیکربندی نشده اند ، و این در مورد نمونه Tinacms من صادق است. اما اگر چنین بود ، این همان چیزی است که هنگام ایجاد مقاله جدید وبلاگ ، درخواست اطلاع داده می شود:
subscription {
newBlog {
title
}
}
مقیاس های سفارشی
پنج ماه بعد از اینکه من در ابتدا این مقاله را نوشتم ، با Magidoc به مسئله ای رسیدم. ساخت Doc با تعاریف گمشده برای مقیاس های سفارشی ناکام بود. در ابتدا ، من فکر می کردم این یک اشکال است ، اما معلوم می شود که این اشکال این بود که نسخه قبلی حتی اگر تعاریف از دست رفته باشد ، اسناد را بسازد. نیازی به ارائه تعاریفی برای مقیاسهای از پیش تعریف شده نیست (Stringبا Intبا Floatبا Boolean وت ID). اما اگر در طرحواره خود مقیاس های سفارشی دارید ، باید نمونه ای برای هر یک در قالب JSON در پرونده پیکربندی Magidoc ارائه دهید. این تعاریف تحت options در website بخش:
website: {
template: 'carbon-multi-page',
customStyles: ['/static/css/custom.css'],
options: {
queryGenerationFactories: {
accountID: "01234567-890a-bcde-f012-34567890abcd",
}
}
}
پایان
این فراتر از محدوده این مقاله است که بیشتر از پوشش اصول اولیه انجام شود. برای اطلاعات بیشتر ، Documenation GraphQL نقطه شروع خوبی است. Tinacms یک برنامه خوب برای شروع آزمایش با API GraphQL آن است. برای ماجراجویانه ، Kingdom Orjiewuru قسمت اول مقاله ای را در مورد ساختن یک مدیر اسناد ساده با GraphQL نوشت.
