معالجة الأخطاء التي تحترم مستخدميك

معظم معالجة الأخطاء تُكتب للمهندس الذي يعرف النظام بالفعل.

هذا معكوس.

المستخدم لا يهمه أن مهلة webhook من Stripe قد انتهت، أو أن سياسة Supabase رفضت الصف، أو أن مزود النموذج أعاد 429. يهتم بثلاثة أشياء:

• ماذا حدث
• هل عمله آمن
• ماذا يمكنه فعله بعد ذلك

إذا لم تستطع الواجهة الإجابة عن هذه الأسئلة، فإن رسالة الخطأ لا تساعد. إنها فقط تُسرّب تفاصيل التنفيذ.

ابدأ بمهمة المستخدم، لا بالاستثناء

المسودة الأولى لرسالة الخطأ عادةً ما تبدو كمسار الكود:

فشل إنشاء جلسة الدفع.

قد يكون هذا صحيحًا، لكنه ليس مفيدًا. نسخة أفضل تبدأ بنية المستخدم:

لم نتمكن من فتح الدفع. تم حفظ تفاصيل مشروعك. حاول مرة أخرى، أو احجز مكالمة وسننهيها يدويًا.

تلك الرسالة تؤدي أربع مهام:

• تسمي الإجراء الفاشل
• تؤكد ما إذا كانت البيانات محفوظة
• تعطي خطوة تالية
• تتجنب إلقاء اللوم على المستخدم

لا يزال من الممكن تسجيل الخطأ الداخلي مع المزود، رمز الحالة، معرف الطلب، وتتبع الاستدعاء. المستخدم لا يحتاج كل ذلك.

افصل نص المستخدم عن القياسات الهندسية

يجب ألا يحمل سطح المنتج وسطح المراقبة نفس الحمولة.

في الإنتاج، أريد مخرجين من نفس الفشل:

• رسالة قابلة للقراءة البشرية على الصفحة
• حدث قابل للقراءة الآلية في السجلات، التحليلات، والتنبيهات

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

حالات الخطأ الجيدة تجيب عن خمسة أسئلة

عندما أراجع حالة خطأ، أمررها عبر قائمة التحقق هذه.

إذا كانت الإجابة لا، فإن الحالة لم تكتمل.

على سبيل المثال، فشل نموذج عميل محتمل لا يجب أن يقول 500 Internal Server Error. يجب أن يقول شيئًا أقرب إلى:

لم نتمكن من إرسال الرسالة. بقي متصفحك على هذه الصفحة، لذا لم يُفقد شيء. حاول مرة أخرى أو أرسل تفاصيل المشروع مباشرة عبر البريد الإلكتروني.

ثم يجب أن تحمل سجلات الخادم السبب الفعلي: فشل التحقق، انتهاء مهلة Resend، فشل إدراج Supabase، أو رفض webhook.

صمم المسار البديل قبل فشل النظام

عادةً ما تضيف الفرق حالات البديل بعد أول حادثة إنتاج. هذا مكلف لأن الفشل أصبح علنيًا بالفعل.

بالنسبة للتدفقات المهمة، أحب تعريف المسار البديل أثناء بناء الميزة:

لا يحتاج البديل أن يكون فاخرًا. يحتاج إلى الحفاظ على الزخم.

لا تجعل كل خطأ يبدو متشابهًا

الرسائل العامة تجعل المنتج يبدو مهملاً:

• حدث خطأ ما.
• حاول مرة أخرى لاحقًا.
• حدث خطأ غير متوقع.

أحيانًا تكون هذه مقبولة كشبكة أمان نهائية، لكن لا ينبغي أن تكون لغة الخطأ الوحيدة في المنتج.

الأخطاء المختلفة تحتاج مسارات استرداد مختلفة:

• خطأ التحقق: أظهر الحقل المحدد والتنسيق المتوقع
• خطأ الإذن: اشرح الدور أو الحساب المطلوب
• حد المعدل: قل متى يعيد المحاولة أو قدم إجراءً أخف
• فشل التبعية: احفظ عمل المستخدم وأظهر مسارًا بديلاً
• فشل الإجراء التدميري: اذكر بوضوح ما لم يتغير

الهدف ليس جعل النظام يبدو مثاليًا. الهدف هو جعل المستخدم يشعر بالتوجيه عندما لا يكون النظام مثاليًا.

المشغل يحتاج واجهة مختلفة

نص المستخدم المحترم يعمل فقط إذا حصل المشغل على الأدلة الحقيقية.

هذا يعني تسجيل:

• المسار والإجراء
• معرف الطلب أو التتبع
• معرف المستخدم/المؤسسة عند توفره
• المزود ورمز الحالة
• شكل الحمولة الآمن
• التوقيت
• عدد مرات إعادة المحاولة

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

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

النمط الذي أحاول شحنه

لكل إجراء مهم، أريد هذا الشكل:

1. تحقق مبكرًا وأظهر إرشادات على مستوى الحقل.
2. لف إجراء الخادم/مسار API في معالجة أخطاء منظمة.
3. أعد رسالة مستخدم ثابتة ورمز آلة ثابت.
4. سجل السياق الكامل الآمن للمشغل.
5. تتبع الفشل كحدث منتج إذا كان يؤثر على التحويل.
6. احتفظ بمدخلات المستخدم حيثما أمكن.

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