پرسوجوی نامدار با متغیر
شناسه را بهصورت متغیر ورودی بفرستید؛ این الگو از چسباندن مقدار کاربر به متن query جلوگیری میکند.
query UserProfile($id: ID!) { user(id: $id) { id name email }}
مرجع سریع GraphQL برای operation، schema، scalarها، آرگومانها، input type و mutation. در GraphQL کلاینت دقیقاً فیلدهای موردنیاز را در یک operation مشخص میکند. نامگذاری operation، متغیرها و انتخاب صریح فیلدهای تودرتو خواندن درخواست را سادهتر و قرارداد API را قابلآزمون میکند. Schema قرارداد نوعدار سرویس را تعریف میکند: Query نقطهٔ ورود خواندن داده است و نوعهای object، scalar، enum، interface و union شکل خروجی را توصیف میکنند. نوعهای داخلی مانند `ID` و `String` را با نوع دامنهای متناسب ترکیب کنید. از این صفحه بهعنوان مرجع سریع استفاده کنید و مثالها و نکتهها را با نسخهٔ ابزار، نیاز و شرایط واقعی پروژهٔ خود تطبیق دهید.
شناسه را بهصورت متغیر ورودی بفرستید؛ این الگو از چسباندن مقدار کاربر به متن query جلوگیری میکند.
query UserProfile($id: ID!) { user(id: $id) { id name email }}هر سطح از پاسخ را با selection set مشخص کنید؛ شیء بدون انتخاب فیلد، پاسخ قابلخواندنی تولید نمیکند.
query { course { title instructor { name } }}Alias نام فیلد پاسخ را تغییر میدهد و برای اجرای یک فیلد با آرگومانهای متفاوت مفید است.
query { latest: course(id: "latest") { title } featured: course(id: "featured") { title }}فیلدهای هر شیء را با نوع خروجی بنویسید و ریشهٔ Query را برای عملیات خواندن تعریف کنید.
type Course { id: ID! title: String! duration: Int}type Query { courses: [Course!]!}Int، Float، String، Boolean و ID نوعهای پایهٔ GraphQL هستند؛ برای دادهٔ مالی دقیق از Float بهعنوان جایگزین نوع decimal استفاده نکنید.
type Product { id: ID! title: String! quantity: Int! available: Boolean! rating: Float}Enum مجموعهٔ مقدارهای محدود را تعریف میکند؛ interface قرارداد فیلد مشترک و union یکی از چند نوع ممکن را نمایش میدهد.
enum CourseLevel { BEGINNER INTERMEDIATE ADVANCED}interface Node { id: ID!}union SearchResult = Course | InstructorString میتواند null باشد، اما String! مقدار تهی را نمیپذیرد؛ همین قاعده برای اعضای list نیز جداگانه تعیین میشود.
type Example { optionalName: String requiredName: String! nullableItems: [String] requiredItems: [String!]!}نوع آرگومان را در schema ثبت کنید و مقدار متغیر را در operation ارسال کنید؛ مقدار پیشفرض فقط برای ورودی واقعاً اختیاری است.
type Query { courses(limit: Int = 10, level: CourseLevel): [Course!]!}query Courses($limit: Int!, $level: CourseLevel) { courses(limit: $limit, level: $level) { id title }}برای فیلتر یا دادهٔ ورودی چندفیلدی از نمونهٔ زیر استفاده کنید؛ نوع object معمولی را بهعنوان ورودی mutation بهکار نبرید.
input CourseFilter { search: String level: CourseLevel limit: Int = 20}type Query { courses(filter: CourseFilter): [Course!]!}ورودی را به شکل input type بگیرید و نتیجهٔ ایجادشده را برگردانید تا کلاینت نیازی به درخواست اضافی نداشته باشد.
input CreateCourseInput { title: String! level: CourseLevel!}type Mutation { createCourse(input: CreateCourseInput!): Course!}fragment را برای selectionهای تکراری بهکار ببرید؛ نام و محل تعریف آن را طوری انتخاب کنید که نوع هدف روشن بماند.
fragment CourseSummary on Course { id title duration}query { courses { ...CourseSummary }}@include و @skip انتخاب فیلد را براساس متغیر شرطی میکنند؛ آنها جایگزین مجوزدهی سمت سرور نیستند.
query CourseDetails($showInstructor: Boolean!) { course(id: "web-101") { title instructor @include(if: $showInstructor) { name } }}در operation فقط فیلدهای لازم را انتخاب و queryهای مهم را نامگذاری کنید.
نوعهای Query و Mutation نقطههای ورود خواندن و تغییر داده را مشخص میکنند.
با ID!، String! و listها تهیپذیری ورودی و خروجی را دقیق تعریف کنید.
برای مقدارهای ورودی مرکب از input و برای مجموعهٔ بسته از enum استفاده کنید.
Scalarهای داخلی شامل Int، Float، String، Boolean و ID هستند.
برای انتخابهای تکراری fragment بسازید و برای تفاوت پاسخ از alias استفاده کنید.
مجوزدهی را در resolver یا لایهٔ سرویس سمت سرور انجام دهید؛ directive شرطی امنیت ایجاد نمیکند.
محدودیت عمق، تعداد و هزینهٔ query را برای endpoint عمومی ارزیابی کنید.
در API عمومی عمق و هزینهٔ query، اندازهٔ صفحه و تعداد aliasها را محدود کنید تا یک درخواست سنگین منابع سرویس را اشغال نکند.
مجوز دسترسی را برای هر منبع در سرور بررسی کنید؛ مخفیکردن فیلد یا استفاده از @include جای authorization را نمیگیرد.