معمارية البرمجيات / الأساسيات: الوعود والبنية والملكية / الدرس 5
حدّد عقودا تتحمل التغيير المستقل
صِف معنى الطلب والتوافق والأخطاء والنتائج المجهولة بما يتجاوز مخطط الاستجابة الناجحة.
في هذه الصفحة
أهداف الدرس
- ميّز توافق الصياغة عن الحفاظ على السلوك.
- حدّد التطور الإضافي وحدود التحقق ودلالات الأخطاء.
يشمل العقد أكثر من أسماء الحقول
يصف عقد الواجهة ما يطلبه المستدعي ومعاني النتائج وضمانات المزود ضمن شروط معينة. في الحجز تهم الوحدات والهوية والتكرار ونطاق التفويض وتمثيل الزمن بقدر أنواع حقول JSON. يجب أن تقابل confirmed حالة عمل مرجعية، لا مجرد إدخال إلى طابور. وثّق إمكان الإلغاء والاستعلام وإعادة العملية المجهولة. يستطيع مدقق المخطط فحص البنية، لكنه لا يثبت احترام التنفيذ للوعود الدلالية.
اجعل القيم الملتبسة صريحة
يستخدم المثال معرف ورشة معتما وعددا صحيحا للمقاعد وهوية طلب عميل ثابتة. ويتجنب اعتبار سعر يرسله العميل مرجعا. ويحتاج التنفيذ الحقيقي حدود طول ونطاقات وربط هوية وقرار تفويض. إذا وصلت هوية الطلب نفسها بمدخلات مختلفة، فرفض التعارض أوضح من إعادة نتيجة لا تخصها. حدّد مدة الاحتفاظ بسجلات منع التكرار ليعرف العميل متى لا تحمل إعادة هوية قديمة الضمان نفسه.
{"request_id":"req-17","workshop_id":"ws-42","seats":1}هذا الطلب JSON صحيح الصياغة. تعتمد صحته التجارية على عقد المزود؛ ولا يغني المعرف عن المصادقة أو يسمح بالوصول إلى الورشة.
افصل الرفض والفشل والغموض
يختلف رفض معروف مثل نفاد السعة عن عطل داخلي وعن مهلة اتصال بعد تثبيت مجهول. قدّم رموز أخطاء ثابتة قابلة للقراءة آليا ووصفا آمنا مفيدا. لا تُجبر العميل على تحليل النثر أو استثناءات القاعدة أو النص المترجم. حدّد ما يمكن إعادته وبأي هوية وموعد نهائي. تنقل حالات HTTP معنى بروتوكوليا عاما ويضيف خطأ المجال السياق. وقد تربك استجابة نقل ناجحة تحمل علما غير مفسر للخطأ الرصد والعميل ما لم يحدد العقد ذلك عمدا.
تعامل بحذر مع الحقول الاختيارية وتوسع القيم
قد تكون إضافة حقل متوافقة إذا تجاهل المستهلك القديم المجهول وتقبل الجديد غيابه. وهذا افتراض يُختبر، لا خاصية عامة في JSON. وقد تكسر قيمة تعداد جديدة منطق العميل الشامل؛ وقد يغير الانتقال من غياب الحقل إلى null معناه. تضيف الاستجابة المقترحة تسمية عرض اختيارية وتحفظ المعرفات ومعنى التأكيد. اختبر المستهلك القديم مع الرد الجديد والجديد مع القديم حين ينتج النشر التدريجي كلا التركيبين.
{"reservation_id":"r-8","status":"confirmed","display_label":"Workshop booking"}يعتمد التوافق على سلوك المستهلك. display_label بيانات عرض اختيارية توضيحية؛ ويحفظ الحقلان الآخران المعنى السابق، ولا تدعي الوثيقة تنفيذ اختبار مستهلك.
طوّر العقد بأدلة انتقال
أصدر نسخة للعقد عندما يتعذر إدخال تغيير كاسر بمراحل متوافقة. انشر السلوك البديل وفترة التداخل وفحوص الانتقال ومالك الإيقاف. ميّز نسخة الواجهة عن إصدار التطبيق؛ فلا يتطلب كل بناء جديد واجهة عامة جديدة. راقب استخدام المستهلكين حيث يُسمح وقدّم تراجعا يحترم البيانات المكتوبة بالصورة الجديدة. لا يثبت إشعار الإهمال وحده انتقال الجميع، خاصة للعملاء غير المتصلين والمهام قليلة التكرار.
الأخطاء الشائعة وإصلاحها
تحلل التطبيقات جملة خطأ مترجمة.
- لماذا يحدث؟
- أصبح نص العرض عقدا آليا.
- كيف تصلحه؟
- أضف رموزا ثابتة وافصل النص المحلي.
- كيف تتجنب تكراره؟
- اختبر الرموز والدلالات بدلا من الصياغة.
تعطل قيمة تعداد جديدة المستهلكين القدماء.
- لماذا يحدث؟
- افتُرض أن الإضافات البنيوية آمنة سلوكيا.
- كيف تصلحه؟
- حدّد معالجة القيم المجهولة أو انتقالا متوافقا.
- كيف تتجنب تكراره؟
- ضمّن تركيبات العملاء القديمة والجديدة في المراجعة.
تُعرض المهلة كرفض مؤكد.
- لماذا يحدث؟
- اختلط دليل النقل بنتيجة العمل.
- كيف تصلحه؟
- قدّم استعلام نتيجة أو إعادة آمنة متكررة الأثر.
- كيف تتجنب تكراره؟
- نمذج النتائج المجهولة صراحة في العميل.
اختبر فهمك
1. هل يجعل حقل request_id الحجز متكرر الأثر وحده؟
اعرض الحل المشروح
لا. يجب أن يربط المزود الهوية بالمستدعي والمدخلات، ويخزن النتيجة ذريّا مع الحجز، ويحدد التزامن والاحتفاظ. وعلى العميل إعادة الهوية للعملية نفسها. مجرد قبول سلسلة لا يمنع التنفيذ المكرر أو المدخلات المتعارضة.
2. أعاد مطور تسمية confirmed إلى accepted دون تغيير نوع المخطط. هل هذا متوافق؟
اعرض الحل المشروح
قد يكسر المستهلك الذي يطابق القيمة القديمة ويغير الوعد من حجز مكتمل إلى طلب مقبول. قارن الصياغة والمعنى معا. احفظ القيمة القديمة أثناء الانتقال أو أصدر نسخة صريحة للتغيير الدلالي الكاسر، وقدّم اختبارات تثبت الانتقال المختار.
أهم ما تعلمته
- التوافق خاصية للتنفيذات المتفاعلة ومعانيها.
- يجب أن يشرح العقد الفشل والغموض بعناية توازي النجاح.