ما يظهره الكوربوس
تتلاقى الكتابات المؤسسية عن الوكلاء في الإنتاج عند مجموعة ضيقة من الإخفاقات، ومعظمها ليست إخفاقات نموذج. إنها إخفاقات واجهة. يظهر الاحتكاك نفسه عبر عمليات نشر غير مترابطة:
- الأدوات تُرجع نجاحًا غير منظم. استجابة مثل
{"status": "ok"}أو HTTP 200 مجردة مع جسم مقروء للبشر تترك الوكيل ليستنتج ما إذا كان الأثر المقصود قد حدث فعلًا. - الفشل الجزئي مخفي. عملية دفعية عالجت بعض العناصر وتخطت أخرى تُبلّغ عن النجاح لأن النقل نجح.
- نية واحدة تتطلب طقسًا متعدد الاستدعاءات. إنشاء مورد يعني استدعاء نقطة إنشاء، ثم استقصاء نقطة حالة، ثم استدعاء نقطة إنهاء. كل استدعاء فرصة للتوقف في المنتصف، والحالات الوسيطة غير ممثلة في أي مكان في وصف الأداة.
- إعادة المحاولات تُنفَّذ ضد نقاط لا تشير أبدًا إلى حالة نهائية. تصف تقارير الحوادث وكلاء يدورون في حلقة على استدعاء يظل يُرجع خطأ يبدو عابرًا، لأن لا شيء في الاستجابة يميز بين "حاول مرة أخرى" و"هذا لن ينجح أبدًا".
النمط ثابت: يُطلب من سطح الأداة أن يحمل دلالات لم يُصمم أبدًا للتعبير عنها. الوكيل لا يسيء التصرف بقدر ما يكمل التفسير الوحيد الذي تسمح به الواجهة.
مغالطة الغلاف
لف واجهة برمجة بشرية موجودة في مخطط JSON لا ينتج سطح أداة. إنه ينتج استدعاء إجراء عن بُعد مع وصف رقيق. يخبر المخطط النموذج بالحقول التي يرسلها؛ لكنه لا يقول تقريبًا شيئًا عن معنى الاستدعاء، أو متى يكون صالحًا، أو ما تعنيه استجابة معينة عن العالم.
واجهات البرمجة البشرية مصممة لقارئ يستطيع التعويض عن المعلومات الناقصة. ذلك القارئ يمكنه استنتاج النية من السياق المحيط، أو سؤال زميل عن معنى رمز حالة، أو ملاحظة أن نتيجة تبدو قديمة والتحقيق فيها. لا يوجد أي من مسارات التعافي هذه لوكيل يعمل داخل حلقة. عندما تكون الواجهة غامضة، تكون الاستراتيجية الوحيدة المتاحة للوكيل هي التخمين أو إعادة المحاولة أو التخلي، وكلها مكلفة في الإنتاج.
كما يستورد نهج الغلاف افتراضات لا تنجو من الترجمة. قد تعامل واجهة برمجة بشرية استجابة 200 مع جسم خطأ كعرف يعرفه كل فرد في الفريق. قد تعامل قائمة فارغة إما كـ "لا نتائج" أو "الاستعلام كان مشوهًا"، لأن إنسانًا سيتحقق. قد تترك العمليات المدمرة غير متكافئة لأن إنسانًا لن ينقر الزر مرتين. كل من هذه قرار تصميم معقول لمستدعٍ بشري وعيب لمستدعٍ آلي.
ما يحتاجه الوكلاء بدلًا من ذلك هو سطح بشروط مسبقة صريحة، وشروط لاحقة صريحة، وتصنيف أخطاء نهائية. الشرط المسبق يحدد ما يجب أن يكون صحيحًا قبل أن يكون الاستدعاء صالحًا. الشرط اللاحق يحدد ما سيكون صحيحًا بعد استدعاء ناجح. تصنيف الأخطاء النهائية يحدد أي الإخفاقات قابلة لإعادة المحاولة، وأيها دائم، وأيها يتطلب استدعاءً مختلفًا تمامًا.
استدعاء أداة واحد، نية واحدة
يجب أن يعبر استدعاء الأداة عن نية واحدة. إذا كان تحقيق هدف واحد يتطلب سلسلة استدعاءات بلا طريقة للاستئناف، فإن السطح يدعو إلى إكمال جزئي وإعادة محاولات غامضة. حيث تكون العملية متعددة الخطوات لا مفر منها، مثّل الحالات الوسيطة صراحة واجعل كل انتقال عملية من الدرجة الأولى بشروطها المسبقة الخاصة، بدلًا من إخفائها خلف طقس يُتوقع من المستدعي تنفيذه بشكل صحيح.
كل استجابة هي واحدة من ثلاثة أشياء
يجب أن تكون كل استجابة قابلة للتصنيف كنجاح، أو فشل قابل لإعادة المحاولة، أو فشل نهائي. لا توجد حالة رابعة. الاستجابة الغامضة تجبر المستدعي على اختراع سياسة، والسياسات المخترعة هي مصدر عواصف إعادة المحاولة. عمليًا، هذا يعني غلاف استجابة بمجموعة صغيرة ومغلقة من أنواع النتائج، وقاعدة تقضي بمعاملة أنواع النتائج غير المعروفة كإخفاقات نهائية بدلًا من إعادة المحاولة.
آلية مفيدة هي غلاف استجابة بمميز نتيجة صريح وتلميح إعادة محاولة محدود:
{
"outcome": "retryable_failure",
"reason": "upstream_unavailable",
"retry_after_ms": 2000,
"observed_state": null
}
الخاصية المهمة ليست أسماء الحقول المحددة بل أن المستدعي يمكنه التفرع دون تفسير. terminal_failure تعني التوقف وإظهار الخطأ. retryable_failure تعني إعادة المحاولة ضمن الحد المذكور. success تعني أن الشرط اللاحق يتحقق.
العمليات المدمرة متكافئة حسب المفتاح
يجب أن تكون العمليات المدمرة متكافئة حسب المفتاح حتى تكون إعادة المحاولات آمنة بالبناء. يقدم المستدعي مفتاح تكافؤ ثابتًا مشتقًا من النية، ويعيد السطح النتيجة نفسها لمفتاح متكرر بدلًا من تنفيذ الأثر مرتين. هذا يزيل حاجة الوكيل إلى التفكير فيما إذا كانت محاولة سابقة قد نجحت، وهو بالضبط التفكير الذي ي
يجب أن تعيد الاستجابة الحالة المرصودة إلى جانب النتيجة المزعومة حتى يتمكن المستدعي من التحقق بدلًا من الثقة. إذا ادعت الأداة أن موردًا قد أُنشئ، فيجب أن تعيد الحالة القابلة للملاحظة الحالية للمورد. يصبح التحقق عندئذ مقارنة يمكن للوكيل إجراؤها، بدلًا من اعتقاد عليه أن يتمسك به. هذا أيضًا ما يجعل نجاح البيانات القديمة قابلًا للكشف: النتيجة المزعومة والحالة المرصودة تتعارضان.
مقايضات صادقة
هذه القواعد ليست مجانية. أغلفة النتائج الصريحة تجعل الاستجابات أكبر، ما يستهلك السياق وقد يدفع وصف الأداة إلى ما بعد النقطة التي ينتبه فيها النموذج بشكل موثوق. مفاتيح التكافؤ تتطلب حالة على الخادم ونافذة احتفاظ، وهو عبء تشغيلي لفرق لم يكن لديها أي منه سابقًا. تقسيم طقس إلى عمليات صريحة قابلة للاستئناف ينتج أدوات أكثر، وأدوات أكثر تعني غموضًا أكبر في الاختيار للمستدعي. سؤال التصميم ليس ما إذا كان يجب دفع هذه التكاليف بل أين يكون نمط الفشل أسوأ بدونها. في معظم أنظمة الإنتاج، إعادة محاولة غامضة أكثر تكلفة من استجابة أكبر.
تداعيات التقييم
إذا كانت أسطح الأدوات هي المشكلة، فإن صحة استدعاء الأداة هي الشيء الخاطئ الذي يُقيَّم على إكمال المهمة وحده. تشغيل يكمل مهمة عبر إعادة المحاولة خلال فشل نهائي ليس تشغيلًا صحيحًا؛ إنه تشغيل حالفه الحظ ضد سطح فشل في التواصل. يجب أن يفصل التقييم بين بُعدين:
- ربط النية بالاستدعاء. هل اختار الوكيل الأداة الصحيحة بالوسائط الصحيحة للنية المذكورة، بما في ذلك الحالات التي يكون فيها السلوك الصحيح هو عدم استدعاء أي شيء؟
- معالجة فئات الفشل. لكل فئة فشل يمكن للسطح إصدارها، هل استجاب الوكيل بالسياسة الصحيحة: إعادة المحاولة ضمن الحد، أو التوقف والإظهار، أو التبديل إلى استدعاء مختلف؟
هذا يعني أن مجموعات الانحدار تحتاج إلى استجابات أدوات خصمية كعناصر اختبار من الدرجة الأولى، لا كتجارب فوضى عرضية. الأربعة الأكثر أهمية هي النجاح البطيء، والنجاح الجزئي، والفشل الصامت، والنجاح مع بيانات قديمة. كل واحد منها يستقصي افتراضًا مختلفًا:
- النجاح البطيء يختبر ما إذا كانت سياسة المهلة لدى الوكيل تميز بين الكمون والفشل.
- النجاح الجزئي يختبر ما إذا كان يقرأ الحالة المرصودة بدلًا من النتيجة المزعومة.
- الفشل الصامت يختبر ما إذا كان يتحقق من الشروط اللاحقة أصلًا.
- النجاح مع بيانات قديمة يختبر ما إذا كان يقارن الطوابع الزمنية أو الإصدارات بدلًا من الثقة بالاستجابة.
السطح الذي لا يستطيع إنتاج هذه الاستجابات في بيئة اختبار هو سطح أنماط فشله غير معروفة حتى تظهر في الإنتاج. بناء عناصر الاختبار جزء من بناء الواجهة.
خاتمة
أسطح الأدوات مشكلة تصميم واجهات. يتعامل نهج الغلاف مع الواجهة كطبقة ترجمة فوق واجهة برمجة بشرية موجودة، ويرث كل افتراض افترضته تلك الواجهة عن قارئ يستطيع التعويض. التصميم لمستدعٍ آلي يعني جعل الشروط المسبقة، والشروط اللاحقة، ودلالات الأخطاء النهائية صريحة، وقبول التكاليف التي تأتي مع ذلك. البديل هو نظام لا يمكن تمييز إخفاقاته عن نجاحاته حتى يقرأ أحدهم السجلات.