GraphQL / المتقدم: التنفيذ المحدود والموزع / الدرس 18

حوكمة المخطط وملفات البناء ومراجعة الإصدار

اربط المخطط والعمليات والسياسات وآثار البناء وأدلة الاختبار في عقد إصدار يستطيع المراجع فحصه وإعادة التحقق منه.

وقت القراءة التقريبي: 5 دقيقةتاريخ مراجعة المحتوى 2026-10-28

في هذه الصفحة

أهداف الدرس

حدد الملكية وفحوص آثار المخطط والوثائق الموثوقة.
افصل ميزات المواصفة المستقرة عن الخاص والتجريبي.

عين مسؤولاً عن كل قدرة عامة ومعناها

قد ينمو الرسم إلى مجموعة حقول غير موثقة إذا راجع الفريق كل محلل باعتباره كوداً محلياً فحسب. عين مسؤولين عن معنى المجال، والتفويض، والكلفة، والتوافق. ينبغي أن تسأل مراجعة الإصدار: أي عملاء مدعومين يستخدمون إحداثي المخطط المتغير، وما سلوك المصدر الذي يستدعيه، وما النتيجة التي يتلقاها المستدعي عند الفشل؟ اشرح في التوثيق لماذا يوجد الحقل وما ضماناته العملية، بدلاً من تكرار اسم نوعه. تشمل الملكية أيضاً إنهاء الميزات القديمة بقصد واضح، وتوفير مسار تصعيد عندما تعبر عملية مركبة حدود مسؤولية أكثر من مجال.

احفظ مدخلات إصدار محددة قابلة للفحص

يربط السجل التالي نسخة محددة من ملف المخطط المرجعي بوثائق العمليات وإصدارات السياسات. إنه قائمة مراجعة اصطناعية، ولا يحتوي تجزئات حقيقية أو يدعي اكتمال الاعتماد. في مسار البناء الفعلي، احفظ معرفات لمخرجات بناء غير قابلة للتغيير، وتحقق من اشتقاق أنواع العميل المولدة وسجلات الوثائق الموثوقة من المدخلات نفسها بالضبط. تجنب جلب مخطط حي غير محدد أثناء بناء الإصدار. تسمح مجموعة مخرجات البناء المحددة والحتمية بإعادة التحقق، وتساعد المراجع على تحديد ما إذا كان التراجع سيبقي الحقول ومعرفات الوثائق التي يحتاجها العملاء المنشورون بالفعل.

json سجل اصطناعي لآثار الإصدار وأدلته المطلوبة

{
  "release": "synthetic-portal-review",
  "artifacts": ["schema.graphql", "supported-operations.graphql", "trusted-documents.json"],
  "policies": ["visibility-v1", "cursor-v1", "write-replay-v1"],
  "requiredEvidence": ["compatibility", "operation-fixtures", "demand-bounds", "rollback-combination"]
}

يسمي السجل الآثار والفحوص التي ينبغي جمعها. لا يدعي حدوث إصدار فعلي أو رفع سجل إلى خدمة أو الحصول على موافقة نشر.

وضح حدود المواصفة ودعم التنفيذ

تمثل مواصفة اللغة لشهر سبتمبر 2025 المرجع المستقر المختار لهذا المقرر. وقد تختلف عنها ميزة يوفرها إطار معين، أو مسودة عمل، أو نمط تنفيذ تجريبي من حيث النضج والتوافق. مثلاً، لا تفترض أن @defer تعمل لمجرد أن العميل يستطيع تحليل صياغتها؛ إذ يحتاج تنفيذ الخادم، وتأطير رسائل النقل، ودمج العميل إلى دعم متطابق. تحقق من إصدارات المكتبات الدقيقة ووثائق الميزات الرسمية. تعريف التوجيه في المخطط وحده لا يضيف سلوكاً إلى محرك التنفيذ، ولا يتفاوض على بروتوكول جديد لشكل الاستجابة.

حول مراجعة الحقل إلى أسئلة قابلة للإثبات

قد يبدو حقل مثل enrollmentCount بسيطاً عند قراءة SDL، لكن قرار نشره يعتمد على قواعد الظهور، وكلفة المصدر، ومتطلبات الحداثة، وانتشار الفشل عبر الأنواع. يبقي السجل التالي هذه الأسئلة صريحة من دون وضع حدود عددية عامة. قد يطلب المراجع موائماً لمصدر محدود العمل يفرض التفويض، وعينة تختبر حد قبول null، وفحصاً للعملاء المدعومين قبل قبول الحقل. إذا لم يكن العدد مناسباً لكل مستدع، فاختر قدرة تعبر عن المعنى المسموح في المجال؛ لا تعرض تجميعاً عالمياً بلا قيد ثم تعتمد على أن العملاء سيستخدمونه بمسؤولية.

json أسئلة مراجعة محددة لحقل واحد

{
  "coordinate": "Course.eligibleEnrollmentCount",
  "questions": {
    "visibility": "which-principals-may-read",
    "cost": "bounded-source-plan",
    "freshness": "documented-view-policy",
    "failure": "nullable-boundary-reviewed",
    "compatibility": "supported-operations-checked"
  }
}

يحتاج كل سؤال إلى دليل فعلي قبل الإصدار. هذه وثيقة محلية لتوجيه المراجعة، ولا تغير المخطط أو تمنح أي صلاحية وصول.

راجع السلوك كاملاً وصرح بحدود الأدلة

تجمع المراجعة المكتملة بين تحقق المخطط، وعينات العمليات والمتغيرات، وسياسة الوصول للكائن، وحدود الكلفة، وسلوك أخطاء المصدر، وتسوية حالة العميل، وتوافق التراجع. سجل بوضوح الاختبارات المنفذة وحدود الدمج التي لم تختبر. يتحقق هذا المقرر من نماذج محلية وJSON من دون تشغيل خدمات؛ فهو يقدم أدلة تعليمية لا شهادة صلاحية نشر. قبل تنفيذ مستقل، اختر مكتبة GraphQL الفعلية والنقل وبيئة المصدر، ثم أعد الفحوص المناسبة لتلك الحدود هناك. تظهر الحوكمة الجيدة هذه الافتراضات للقائمين على صيانة النظام لاحقاً، حتى يغيروها بقرار صريح بدلاً من وراثة ضمانات لم يقصدها أحد.

الأخطاء الشائعة وإصلاحها

يعامل توجيه تجريبي كميزة محمولة

لماذا يحدث؟: اختلط وجود الصياغة بدعم متكامل.
كيف تصلحه؟: تحقق من توافق التنفيذ والنقل والعميل.
كيف تتجنب تكراره؟: ثبت الفرضيات ووثق الإصدار الرسمي.

تستعمل الأنواع مخططاً مختلفاً عن النشر

لماذا يحدث؟: جلبت المدخلات مستقلة دون هوية أثر.
كيف تصلحه؟: ولد وتحقق من أثر ثابت واحد.
كيف تتجنب تكراره؟: سجل نسب الآثار في دليل الإصدار.

يفتقد الحقل مالك كلفة وظهور

لماذا يحدث؟: اقتصرت المراجعة على صياغة المحلل.
كيف تصلحه؟: عين مسؤولية المجال قبل النشر.
كيف تتجنب تكراره؟: اطلب ملاحظات سياسة وفشل للحقل.

اختبر فهمك

1. لماذا يراجع سجل الوثائق الموثوقة مع أثر العميل؟

اعرض الحل المشروح

يرسل العميل معرفات وثائق محددة يجب أن يعرفها الخادم. إذا اختلف السجل عن أثر العميل، فقد يرفض عمليات منشورة صحيحة حتى مع توافق المخطط. راجع إنشاء السجل وإطلاقه وفترة التداخل وإمكان التراجع مع أثر العميل، واحتفظ بالمعرفات القديمة المدعومة طوال المدة الموعودة. تطابق التجزئة يثبت هوية الوثيقة، لكنه لا يثبت تفويض المستدعي ولا سلامة قيم المتغيرات التي يرسلها.

2. ماذا ينقص ملاحظة تقول نجحت نماذج JSON كلها؟