ما هي أفضل الممارسات لتصميم schema في GraphQL؟

Question

IT Interview Practice · Accepted Answer

الـ schema الجيّد **مدفوع بالعميل، قابل للـ null افتراضيًا عند الأطراف، وقابل للتطوير دون إصدارات (versions)**. يُنمذج المجال بالمصطلحات التي يستخدمها العملاء فعلًا، لا جداول قاعدة بياناتك.

## القابلية للـ null

اجعل الحقل non-null (`!`) فقط حين تستطيع إعادته *دائمًا*. الإفراط في `!` فخّ: إذا أخطأ حقل non-null، فإنه يجعل كامل كائنه الأب null، محوّلًا فشلًا صغيرًا إلى فراغ كبير. فضّل القابلية للـ null لأي شيء يعتمد على خدمة تابعة (downstream).

```graphql
type User {
  id: ID!             # موجود دائمًا حقًا
  email: String!      # مطلوب في قاعدة بياناتك -> آمن كـ non-null
  avatarUrl: String   # يأتي من خدمة خارجية -> قابل للـ null، فيُعزل فشله
}
```

## التسمية والمُدخلات (inputs)

- استخدم أسماء متسقة ووصفية؛ وتُقرأ القيم المنطقية كمُسنَدات (`isPublished`).
- امنح كل mutation نوع **`input`** واحدًا وأعِد نوع **payload** — فتستطيع إضافة حقول لاحقًا دون كسر التوقيع.

```graphql
input CreatePostInput { title: String!, body: String! }
type CreatePostPayload { post: Post!, errors: [UserError!]! }  # مساحة للنمو
type Mutation { createPost(input: CreatePostInput!): CreatePostPayload! }
```

## التطوير دون إصدارات

يتجنّب GraphQL عناوين `/v2`. تطوّر **بالإضافة**: أضِف حقولًا بحرية، وأحِل القديمة بـ `@deprecated` بينما يهاجر العملاء.

```graphql
type User {
  fullName: String!
  name: String! @deprecated(reason: "Use fullName")   # استمر بالتقديم حتى ينتقل العملاء
}
```

إزالة حقل أو إعادة تسميته هي التغيير الكاسر الوحيد الحقيقي، لذا صمّم بحيث نادرًا ما تحتاج إليه. تجنّب أيضًا تسريب شكل قاعدة البيانات (اعرض `fullName`، لا `first_name`/`last_name` إن كان العملاء يريدون حقلًا واحدًا).

## لماذا يهم

هذه الخيارات هي ما يفصل schema يدوم سنوات عن آخر يصارعه العملاء. يستخدم المُحاورون هذا لقياس **نضج تصميم الـ API** — خاصة مقايضة القابلية للـ null/الخطأ وعقلية التطوير بالإضافة، وهما ميزتان فريدتان في GraphQL.

القابلية للـ null

التسمية والمُدخلات (inputs)

التطوير دون إصدارات

لماذا يهم

أسئلة ذات صلة