עיצוב סכמת GraphQL: טיפוסים, מוטציות, פג'ינציה

עיצוב סכמת GraphQL ליישומי אינטרנט

אנו מעצבים סכמות GraphQL שמשרתות לאורך שנים ללא עקיפות. סכמה גרועה מובילה לשאילתות N+1 שבורות, שדות רפאים, ו-type UserOrError במקום טיפול נכון בשגיאות. הגישה שלנו: תחילה לנתח את צרכי הממשק, ולאחר מכן להגדיר טיפוסים. הניסיון מראה: סכמה מעוצבת היטב מקצרת את זמן הפיתוח של הפרונטאנד ב-30% ומבטלת 90% מבעיות ביצועי השאילתות. חיסכון במשאבי הצוות יכול להגיע ל-40% בשלב האינטגרציה.

הסכמה מונחית מוצר, לא מונחית אחסון. נקודות קצה של REST משקפות לעיתים קרובות את מבנה מסד הנתונים. עם GraphQL, זה הפוך: תחילה קובעים מה הממשק צריך, ואז מעצבים טיפוסים. זה מקצר את זמן העבודה מחדש בחצי בהשוואה ל-REST המסורתי. בהזמנת עיצוב סכמה מאיתנו, אתה מקבל חוזה מוכן לפרונטאנד ולב�קאנד. אנו מבטיחים שהצוות שלך לא יתמודד עם ממשקים לא עקביים.

Nodes ו-Edges לפי מפרט Relay. אם הפרויקט בינוני או גדול יותר, כדאי לאמץ מבנה תואם Relay מההתחלה—זה קובע תקן לפגינציה ומזהים גלובליים. בדרך כלל, זה חוסך 30% מזמן ההסכמה על הממשק בתוך הצוות.

איך להימנע מ-N+1 בסכמת GraphQL?

כל שדה יכול להפעיל שאילתת מסד נתונים נפרדת. ללא אגרגציה, מקבלים את בעיית N+1. הפתרון הוא DataLoader: הוא מאגד בקשות לפי מפתחות. כמו כן, השתמש ב-@cacheControl לקישור ברמת השדה. בפועל, זה מפחית את העומס על מסד הנתונים פי 3–5. לדוגמה, שליפת 100 הזמנות עם פריטים מקוננים ללא DataLoader מייצרת 101 שאילתות; עם אגרגציה, רק 3-4.

למה אנו משתמשים במפרט Relay?

Relay מספק תקן לפגינציה (מבוססת סמן), מזהים גלובליים, ושליפה מחדש. זה מפחית דיונים בתוך הצוות והופך את הסכמה לצפויה. השוואה: פגינציה מבוססת סמן עובדת פי 10 מהר יותר מזו המבוססת על היסט כאשר שולפים מעבר ל-1000 רשומות, מכיוון שהיא לא סורקת את כל מערך התוצאות.

טיפוסים בסיסיים ופגינציה

type Query {
  node(id: ID!): Node
  product(id: ID!): Product
  products(filter: ProductFilter, page: PaginationInput): ProductConnection!
  viewer: User
}

interface Node {
  id: ID!
}

type ProductConnection {
  edges: [ProductEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type ProductEdge {
  node: Product!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

input PaginationInput {
  first: Int
  after: String
  last: Int
  before: String
}

input ProductFilter {
  categoryIds: [ID!]
  priceMin: Decimal
  priceMax: Decimal
  inStock: Boolean
  search: String
  tags: [String!]
}

השוואה בין פגינציה מבוססת סמן לבין פגינציה מבוססת היסט

תבנית Payload למוטציות

לעולם אל תחזיר טיפוס אובייקט חשוף ממוטציה. השתמש בעטיפת payload המכילה את התוצאה ומערך של userErrors.

type CreateOrderPayload {
  order: Order
  userErrors: [UserError!]!
}

type UserError {
  field: [String!]
  message: String!
  code: OrderErrorCode
}

enum OrderErrorCode {
  INSUFFICIENT_STOCK
  INVALID_ADDRESS
  PAYMENT_DECLINED
  PRODUCT_UNAVAILABLE
}

ההבדל בין userErrors לשגיאות GraphQL: userErrors הם שגיאות עסקיות צפויות שהלקוח חייב לטפל בהן. שגיאות GraphQL הן מצבים בלתי צפויים (חריגות, שגיאות רשת).

הנחיות לבקרת גישה וקישור

directive @auth(requires: Role = USER) on FIELD_DEFINITION
directive @rateLimit(max: Int!, window: String!) on FIELD_DEFINITION
directive @cacheControl(maxAge: Int, scope: CacheControlScope) on FIELD_DEFINITION | OBJECT

enum Role {
  ADMIN
  MANAGER
  USER
  GUEST
}

enum CacheControlScope {
  PUBLIC
  PRIVATE
}

# Пример использования
type Query {
  products: ProductConnection! @cacheControl(maxAge: 300, scope: PUBLIC)
  dashboard: DashboardStats! @auth(requires: MANAGER) @rateLimit(max: 60, window: "1m")
}

גרסאות והתיישנות

GraphQL לא מקבל גרסאות דרך URL. במקום זאת, השתמש באבולוציה מתמשכת: שדות חדשים מתווספים, ישנים מסומנים ב-@deprecated. זה מאפשר ללקוחות לבצע מיגרציה ללא שינויים שוברים. לפי מפרט GraphQL, גישה זו נחשבת לפרקטיקה מומלצת.

type Product {
  id: ID!
  name: String!
  price: Decimal @deprecated(reason: "Use `pricing.basePrice` instead")
  pricing: ProductPricing!
  variants: [ProductVariant!]!
}

type ProductPricing {
  basePrice: Decimal!
  salePrice: Decimal
  currency: CurrencyCode!
}

איך לבצע ביקורת על סכמה קיימת ב-3 שלבים

1. מיפוי שדות. אסוף את כל השדות שבהם הלקוח משתמש באמצעות כלים כמו type Query { node(id: ID!): Node product(id: ID!): Product products(filter: ProductFilter, page: PaginationInput): ProductConnection! viewer: User } interface Node { id: ID! } type ProductConnection { edges: [ProductEdge!]! pageInfo: PageInfo! totalCount: Int! } type ProductEdge { node: Product! cursor: String! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String } input PaginationInput { first: Int after: String last: Int before: String } input ProductFilter { categoryIds: [ID!] priceMin: Decimal priceMax: Decimal inStock: Boolean search: String tags: [String!] } . חתוך את אלה שאינם בשימוש.
2. פרופיל ביצועים. מדוד TTFB של כל בקשה עם Apollo Studio או Sentry. זהה שאילתות N+1.
3. אופטימיזציה. יישם DataLoader לשדות קריטיים, הוסף קישור דרך type CreateOrderPayload { order: Order userErrors: [UserError!]! } type UserError { field: [String!] message: String! code: OrderErrorCode } enum OrderErrorCode { INSUFFICIENT_STOCK INVALID_ADDRESS PAYMENT_DECLINED PRODUCT_UNAVAILABLE } . הפחת את מספר ה-joins.

schema/ base.graphql products.graphql orders.graphql users.graphql scalars.graphql directives.graphql 

פיצול סכמה לפי תחומים

לפרויקטים גדולים, הסכמה מפוצלת לקבצים לפי תחום כפי שמוצג למעלה. זה מפשט תחזוקה וסקירה. בפועל, גישה זו מפחיתה את שיעור קונפליקטי המיזוג ב-70%.

מה כלול בעיצוב סכמה סוהר

כולל גם הדרכת צוות על שימוש בסכמה וחודש של תמיכה לאחר ההשקה. קבל ייעוץ—בוא נדבר על הפרויקט שלך.

לוחות זמנים

עיצוב סכמה ליישום בינוני (5-10 ישויות): 3–5 ימים. עם סקירה, תיעוד והסכמה: שבוע. צור קשר כדי לדון בפרויקט שלך—נעריך את ההיקף ונציע פתרון אופטימלי. הזמן עיצוב סכמה סוהר והיפטר מבעיות N+1 וממשקים לא עקביים. לצוות שלנו יש ניסיון של 5+ שנים והוא השלים בהצלחה מעל 100 פרויקטים בתחומים שונים.

GraphQL הוא לא רק טכנולוגיה אלא דיסציפלינה של עיצוב חוזים. אנו מבטיחים שהתוצאה תעמוד במפרט ובציפיות הצוות שלך.