28 يوليو 2025·6 دقيقة قراءة

تصنيف الأخطاء لتطبيقات الأعمال: واجهة متسقة ومراقبة

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

تصنيف الأخطاء لتطبيقات الأعمال: واجهة متسقة ومراقبة

ما الذي يحله تصنيف الأخطاء في تطبيقات الأعمال الحقيقية

تصنيف الأخطاء هو طريقة مشتركة لتسمية وتجميع الأخطاء حتى يتعامل الجميع معها بنفس الأسلوب. بدل أن يخترع كل شاشة وAPI رسائله الخاصة، تحدد مجموعة صغيرة من الفئات (مثل validation أو auth) وقواعد لكيفية عرضها للمستخدمين وفي المراقبة.

بدون هذا الهيكل المشترك، يظهر نفس المشكلة بأشكال مختلفة. قد يظهر الحقل المطلوب المفقود كـ “Bad Request” على الجوال، و"حدث خطأ ما" على الويب، وتتبع استدعاء في السجلات. لا يعرف المستخدمون ما الذي يجب فعله بعد ذلك، وتضيع فرق الاستجابة الوقت في التخمين عما إذا كان خطأ مستخدم، هجومًا، أو انقطاعًا.

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

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

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

نموذج بسيط: فئة، كود، رسالة، تفاصيل

تصبح التصنيفات أسهل في الصيانة عندما تفصل بين أربعة أشياء تختلط غالبًا: الفئة (نوع المشكلة)، الكود (معرّف ثابت)، الرسالة (نص بشري)، والتفاصيل (سياق مُهيكل). لا تزال حالة HTTP مهمة، لكنها لا ينبغي أن تكون القصة كاملة.

الفئة تجيب: «كيف يجب أن تتصرف الواجهة والمراقبة؟» قد يعني 403 "auth" في مكان، بينما قد يكون 403 آخر "policy" إذا أضفت قواعد لاحقًا. الفئة تتعلق بالسلوك، لا بالنقل.

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

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

التفاصيل تجيب: «ما الذي نحتاجه لإصلاحه؟» اجعل التفاصيل مُهيكلة حتى تتفاعل الواجهة معها. بالنسبة لخطأ نموذج، قد تكون أسماء الحقول. بالنسبة لمشكلة اعتماد، قد يكون اسم الخدمة العلوية وقيمة retry-after.

هذا شكل مُدمج تستخدمه فرق كثيرة:

{
  "category": "validation",
  "code": "CUSTOMER_EMAIL_INVALID",
  "message": "Enter a valid email address.",
  "details": { "field": "email", "rule": "email" }
}

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

الفئات الأساسية: validation، auth، rate limits، dependencies

يمكن لمعظم تطبيقات الأعمال البدء بأربع فئات تظهر في كل مكان. إن سمّيتَها وتعاملتَ معها بنفس الطريقة عبر الباك إند والويب والجوال، ستستجيب واجهة المستخدم باستمرار وتصبح المراقبة قابلة للفهم.

التحقق (متوقع)

تحدث أخطاء التحقق عندما يفشل إدخال المستخدم أو قاعدة العمل. هذه حالة طبيعية ويجب أن تكون سهلة الإصلاح: حقول مطلوبة مفقودة، صيغ غير صحيحة، أو قواعد مثل "لا يجوز أن يتجاوز الخصم 20%" أو "يجب أن تكون قيمة الطلب > $0". يجب أن تميّز الواجهة الحقل أو القاعدة بالضبط، لا تعرض تنبيهًا عامًا.

المصادقة مقابل التفويض (متوقعة)

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

حدود المعدل (متوقعة، قائمة على الزمن)

تعني حدود المعدل "طلبات كثيرة جدًا، حاول لاحقًا." تظهر غالبًا أثناء الاستيراد، لوحات التحكم المزدحمة، أو محاولات إعادة متكررة. أضف تلميح retry-after (حتى لو كان "انتظر 30 ثانية")، واجعل الواجهة تتراجع بدلًا من توجيه ضربات متكررة للخادم.

فشل الاعتمادات (غالبًا غير متوقع)

تنتج أخطاء الاعتمادية من خدمات خارجية أو مهلات أو انقطاعات: مزودي الدفع، البريد/SMS، قواعد البيانات، أو خدمات داخلية. لا يمكن للمستخدمين إصلاحها، لذا يجب أن تقدم الواجهة بدائل آمنة (حفظ كمسودة، المحاولة لاحقًا، التواصل مع الدعم).

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

خطوة بخطوة: بناء التصنيف في ورشة عمل واحدة

يجب أن يكون التصنيف صغيرًا بما يكفي لتذكره، لكن صارمًا لدرجة أن فريقين يصنفان نفس المشكلة بنفس الطريقة.

1) إحصر الوقت واختر مجموعة صغيرة

ابدأ بورشة 60 إلى 90 دقيقة. اكتب الأخطاء الأكثر ظهورًا (مدخلات خاطئة، مشاكل تسجيل الدخول، عدد طلبات زائد، انقطاعات طرف ثالث، أخطاء غير متوقعة)، ثم اجمعها إلى 6 إلى 12 فئة يمكن للجميع نطقها دون مراجعة مستند.

2) اتفق على مخطط أكواد ثابت

اختر نمط تسمية يظل مقروءًا في السجلات والتذاكر. اجعله قصيرًا، تجنّب أرقام الإصدارات، واعتبر الأكواد دائمة بمجرد إصدارها. نمط شائع هو بادئة الفئة مع شِرطة وصفية مثل AUTH_INVALID_TOKEN أو DEP_PAYMENT_TIMEOUT.

قبل مغادرة الغرفة، قرر ما الذي يجب أن يتضمنه كل خطأ: فئة، كود، رسالة آمنة، تفاصيل مُهيكلة، ومعرف تتبع أو طلب.

3) اكتب قاعدة واحدة للفئة مقابل الكود

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

4) حدد سلوك افتراضي لكل فئة

قرّر ما يراه المستخدم افتراضيًا. التحقق يميّز الحقول. المصادقة توجه المستخدم لتسجيل الدخول أو تعرض رسالة وصول. حدود المعدل تعرض "حاول بعد X ثانية". فشل الاعتمادية يعرض شاشة إعادة محاولة هادئة. عندما توجد هذه الافتراضات، تتبع الميزات الجديدة منها بدل اختراع تعاملات فردية.

5) اختبر بسيناريوهات حقيقية

نفّذ خمسة تدفقات شائعة (التسجيل، الدفع، البحث، تعديل إداري، رفع ملف) وصنّف كل فشل. إن احتدم الجدل، فغالبًا تحتاج قاعدة أوضح واحدة، لا عشرين كودًا جديدًا.

أخطاء التحقق: اجعلها قابلة للإصلاح للمستخدمين

حوّل الفئات إلى قواعد واجهة
استخدم عمليات AppMaster لتحويل كل فئة خطأ إلى سلوك واجهة واحد وواضح.
ابنِ الآن

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

أخطاء مستوى الحقل ومستوى النموذج مشكلتان مختلفتان. أخطاء مستوى الحقل تُطابق حقلًا واحدًا (البريد الإلكتروني، الهاتف، المبلغ). أخطاء مستوى النموذج تتعلق بتركيبة المدخلات (تاريخ البدء يجب أن يسبق تاريخ الانتهاء) أو متطلبات ناقصة (لم يتم اختيار طريقة شحن). يجب أن توضح استجابة الـ API هذا الاختلاف حتى تتصرف الواجهة بشكل صحيح.

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

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

سجّل فشلات التحقق بشكل مختلف عن أخطاء النظام. تريد سياقًا كافيًا لتصحيح الأنماط دون تخزين بيانات حساسة. سجّل معرف المستخدم، معرف الطلب، اسم القاعدة أو الكود، وأي حقول فشلت. بالنسبة للقيم، سجّل ما تحتاجه فقط (غالبًا "موجود/مفقود" أو طول) وعمّها إن كانت حساسة.

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

أخطاء المصادقة والصلاحيات: حافظ على الأمان والوضوح

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

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

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

سلوك الواجهة يجب أن يبقى متوقعًا:

  • Unauthenticated: اطلب تسجيل الدخول واحتفظ بما كان المستخدم يحاول فعله
  • Forbidden: ابقَ في الصفحة وأظهر رسالة وصول، مع إجراء آمن مثل "طلب إذن"
  • حساب معطل أو مُلغى: سجّل الخروج وأظهر رسالة قصيرة بأن الدعم يمكنه المساعدة

للتدقيق، سجِّل ما يكفي للإجابة على "من حاول ماذا ولماذا تم منعه" دون كشف أسرار. سجل مفيد يتضمن معرف المستخدم (إن وُجد)، المؤسسة أو مساحة العمل، اسم الإجراء، معرف المورد، الطابع الزمني، معرف الطلب، ونتيجة فحص السياسة (مسموح/ممنوع). أبقِ التوكنات وكلمات المرور خارج السجلات.

في رسائل الواجهة، لا تكشف أسماء الأدوار أو قواعد الصلاحية الداخلية. "ليس لديك صلاحية الموافقة على الفواتير" أكثر أمانًا من "فقط FinanceAdmin يمكنه الموافقة".

أخطاء حدود المعدل: سلوك متوقع تحت الضغط

انشر حيث يحتاج فريقك
انشر على AppMaster Cloud أو على AWS أو Azure أو Google Cloud حسب حاجة فريقك.
نشر التطبيق

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

تظهر حدود المعدل عادة بأشكال: لكل مستخدم (نقرة متكررة من شخص واحد)، لكل IP (عدة مستخدمين وراء شبكة مكتب واحدة)، أو لكل مفتاح API (تكامل واحد يعمل بشكل مكثف). السبب يهم لأن الحل يختلف.

ما الذي تتضمنه استجابة حدود المعدل الجيدة

يحتاج العملاء لشيئين: أنهم مقيدون، ومتى يعيدون المحاولة. أعد HTTP 429 زائد وقت انتظار واضح (مثلاً Retry-After: 30). أضف كود خطأ ثابت (مثل RATE_LIMITED) حتى تجمع لوحات القيادة الأحداث.

حافظ على رسالة هادئة ومحددة. "طلبات كثيرة جدًا" صحيحة لكن غير مفيدة. "يرجى الانتظار 30 ثانية ثم المحاولة" يحدد التوقعات ويقلل النقرات المتكررة.

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

في المراقبة، كثيرًا ما يبالغ الفرق في رد الفعل. لا تطرق باب شخص لكل 429. تتبَّع المعدلات ونبّه عند ارتفاع غير اعتيادي: قفزة مفاجئة لنقطة نهاية أو مستأجر أو مفتاح API قابلة للفعل.

سلوك الباك إند يجب أن يكون متوقعًا أيضًا. استخدم تراجعًا أسّيًا للمهلات التلقائية، واجعل المحاولات قابلة لإعادة التطبيق (idempotent). لا ينبغي لإجراء "إنشاء فاتورة" أن يخلق فاتورتين إن كانت المحاولة الأولى نجحت فعلاً.

فشل الاعتمادات: تعامل مع الانقطاعات بدون فوضى

اجعل أخطاء المصادقة متوقعة
ميّز بين unauthenticated و forbidden واحرص على رسائل واضحة دون تسريب تفاصيل أمنية.
ابدأ الآن

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

ابدأ بتسمية أشكال الفشل الشائعة: مهلة، خطأ اتصال (DNS، TLS، مرفوض)، و upstream 5xx (bad gateway، service unavailable). حتى إن لم تعرف السبب الجذري، يمكنك التقاط ما حدث والاستجابة باستمرار.

إعادة المحاولة أم الفشل السريع

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

  • أعد المحاولة عندما يكون الخطأ مؤقتًا على الأرجح: مهلات، إعادة ضبط الاتصال، 502/503
  • افشل سريعًا للحالات التي يسببها المستخدم أو الدائمة: 4xx من الاعتماد، بيانات اعتماد غير صحيحة، مورد مفقود
  • حدّ المحاولات (مثلاً 2 إلى 3 محاولات) وأضف تراجعًا بسيطًا
  • لا تعيد المحاولة على إجراءات غير قابلة للتكرار إلا إذا كان لديك idempotency key

سلوك الواجهة والبدائل الآمنة

عند فشل اعتماد، قل ما يمكن للمستخدم فعله بعد ذلك دون لومه: "مشكلة مؤقتة. يرجى المحاولة لاحقًا." إن وُجد بديل آمن، عرضه. مثال: إن كانت Stripe معطلة، دع المستخدم يحفظ الطلب كـ "قيد الانتظار" وأرسل تأكيدًا عبر البريد بدل أن يفقد عربة التسوق.

حِمِ المستخدمين من الإرسالات المكررة. إن نقر المستخدم "ادفع" مرتين أثناء استجابة بطيئة، يجب أن يكتشف النظام ذلك. استخدم مفاتيح idempotency لتدفقات الإنشاء والخصم، أو فحوص حالة مثل "الطلب مدفوع بالفعل" قبل تنفيذ الإجراء ثانية.

للمراقبة، سجّل حقولًا تجيب على سؤال واحد بسرعة: "أي اعتماد يفشل، ومدى خطورته؟" التقط اسم الاعتماد، نقطة النهاية أو العملية، المدة، والنتيجة النهائية (timeout، connect، upstream 5xx). هذا يجعل التنبيهات ولوحات القيادة ذات معنى بدلًا من الضجيج.

اجعل المراقبة والواجهة متسقة عبر القنوات

لا تعمل التصنيفات ما لم تتحدث كل قناة نفس اللغة: الـ API، واجهة الويب، تطبيق الجوال، وسجلاتك. وإلا يظهر نفس المشكلة كخمس رسائل مختلفة، ولا يعرف أحد إن كانت خطأ مستخدم أو انقطاع حقيقي.

عامل رموز حالة HTTP كطبقة ثانوية. تساعد في البروكسيات وسلوك العميل الأساسي، لكن الفئة والكود يجب أن يحملان المعنى. قد تبقى مهلة اعتماد على 503، لكن الفئة تخبر الواجهة بأن تعرض "حاول مرة أخرى" وتخبر المراقبة أن تبدّل فريق الاستجابة.

اجعل كل API يعيد شكل خطأ قياسي واحد، حتى عندما يكون المصدر مختلفًا (قاعدة بيانات، وحدة مصادقة، API طرف ثالث). شكل بسيط كهذا يحافظ على تعامل الواجهة ولوحات القيادة ثابتة:

{
  "category": "dependency",
  "code": "PAYMENTS_TIMEOUT",
  "message": "Payment service is not responding.",
  "details": {"provider": "stripe"},
  "correlation_id": "9f2c2c3a-6a2b-4a0a-9e9d-0b0c0c8b2b10"
}

معرّفات التطابق (correlation IDs) هي الجسر بين "المستخدم رأى خطأ" و"يمكننا تتبعه". اعرض correlation_id في الواجهة (زر نسخ مفيد)، وسجّله دائمًا على الخادم لتتبع الطلب عبر الخدمات.

اتفق على ما المطلوب عرضه في الواجهة مقابل ما يُترك في السجلات. تقسيم عملي هو: الواجهة تحصل على الفئة، رسالة واضحة، وخطوة تالية؛ السجلات تحصل على تفاصيل تقنية وسياق الطلب؛ كلاهما يشارك correlation_id والكود الثابت.

قائمة تحقق سريعة لنظام أخطاء متسق

وِحّد استجابة الأخطاء
مَكدِن شكل استجابة الأخطاء في API بمعلومات مُهيكلة حتى تتصرف العملاء بتوقع.
أنشئ الواجهة الخلفية

الاتساق ممل لكن في أحسن حالاته: كل قناة تتصرف بنفس الطريقة، والمراقبة تقول الحقيقة.

تحقق من الباك إند أولًا، بما في ذلك الوظائف الخلفية (background jobs) والويب هوكس. إن كان أي حقل اختياريًا، سيتخطاه الناس وتنكسر الاتساق.

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

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

اختبار بسيط هو إثارة خطأ واحد من كل فئة في بيئة staging والتحقق أن النتيجة نفسها في تطبيق الويب، تطبيق الجوال، ولوحة الإدارة.

أخطاء شائعة وخطوات عملية تالية

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

نماذج الفشل الشائعة:

  • تسريب نص استثناء داخلي للمستخدم. يربك الناس وقد يكشف تفاصيل حساسة.
  • وسم كل 4xx كـ "validation." نقص إذن ليس مثل حقل مفقود.
  • ابتكار أكواد جديدة لكل ميزة دون مراجعة. يتراكم لديك 200 كود تعني نفس 5 أشياء.
  • إعادة المحاولة على الأخطاء الخاطئة. إعادة محاولة خطأ صلاحية أو بريد إلكتروني خاطئ تخلق ضجيجًا.

مثال بسيط: مندوب مبيعات يرسل نموذج "إنشاء عميل" ويحصل على 403. إن تعاملت الواجهة مع كل 4xx كتحقق، فستميّز حقول عشوائية وتطلب منهم "تصحيح المدخلات" بدلًا من إبلاغهم أنهم بحاجة لصلاحية. ثم تُظهر المراقبة ارتفاعًا في "مشاكل التحقق" بينما المشكلة الحقيقية هي الأدوار.

خطوات عملية قصيرة تتناسب مع ورشة واحدة: اكتب وثيقة تصنيف من صفحة واحدة (الفئات، متى تستخدمها، 5–10 أكواد نموذجية)، عرف قواعد الرسائل (ماذا يرى المستخدم مقابل ما يُسجل)، أضف بوابة مراجعة خفيفة للأكواد الجديدة، عيّن قواعد إعادة المحاولة حسب الفئة، ثم نفّذ شاملًا (استجابة الباك إند، خرائط الواجهة، ولوحات المراقبة).

إذا كنت تبني باستخدام AppMaster (appmaster.io)، فالمركزة لهذه القواعد في مكان واحد تساعد على أن يسري نفس سلوك الفئة والكود عبر الباك إند، تطبيق الويب، والتطبيقات النيتيف.

الأسئلة الشائعة

متى يستحق إنشاء تصنيف للأخطاء؟

ابدأ عندما يخدم نفس الباك إند أكثر من عميل واحد (ويب، جوال، أدوات داخلية)، أو عندما يكرر الدعم وما في حالة الطوارئ السؤال: «هل هذه خطأ مستخدم أم مشكلة نظام؟» سيسدّ التصنيف فجوة بسرعة بمجرد أن يكون لديك مسارات متكررة مثل التسجيل، الدفع، الاستيراد، أو تعديلات المدير حيث يصبح التعامل المتسق ذا قيمة.

كم عدد فئات الأخطاء التي نبدأ بها؟

قاعدة جيدة هي البدء بـ 6–12 فئة يمكن للناس تذكرها دون الرجوع إلى المستندات. اجعل الفئات ثابتة وواسعة (مثل validation، auth، rate_limit، dependency، conflict، internal)، واعبر عن الحالة المحددة باستخدام كود، لا بإضافة فئة جديدة.

ما الفرق بين فئة الخطأ وكود الخطأ؟

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

هل يجب أن تكون الرسالة هي نفسها كود الخطأ؟

عامل الرسائل كمحتوى، لا كمُعرفات. أعد رسالة قصيرة وآمنة للمستخدم للواجهات، واعتمد الكود الثابت للتجميع والأتمتة. إن احتجت نصًا تقنيًا أكثر، فضعه في السجلات واربطه بنفس معرف التطابق (correlation ID).

ما الذي يجب أن تتضمنه كل استجابة خطأ من API؟

ضمّن فئة، كود ثابت، رسالة آمنة للمستخدم، تفاصيل مُهيكلة، ومعرف تتبع أو طلب. صغ التفاصيل بحيث يستطيع العميل التصرف (أي حقل فشل أو كم ثانية للانتظار) من دون إسقاط نص استثناء خام.

كيف نجعل أخطاء التحقق قابلة للتنفيذ بدلًا من عامة؟

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

كيف نتعامل مع أخطاء “غير مسجل” مقابل “بدون إذن”؟

Unauthenticated تعني أن المستخدم غير مسجّل الدخول أو أن الجلسة/التوكن غير صالح، لذلك يجب أن توجهه الواجهة لإعادة تسجيل الدخول مع الحفاظ على ما كان يحاول فعله. Forbidden تعني أنه مسجّل الدخول لكنه يفتقر للصلاحية، فتبقى الواجهة في الصفحة وتعرض رسالة وصول دون كشف تفاصيل حساسة.

ما هي الطريقة الصحيحة لتنفيذ أخطاء حدود المعدل؟

أعد قيمة زمنية واضحة لإعادة المحاولة (مثال: retry-after) واجعل الكود ثابتًا حتى تنفّذ العملاء تراجعًا متناسقًا. في الواجهة، امنع النقرات المتكررة وأظهر خطوة واضحة تالية، لأن المحاولات التلقائية السريعة عادة تزيد من المشكلة.

متى يجب إعادة محاولة فشل الاعتماد، وكيف نتجنب التكرارات؟

أعد المحاولة فقط عندما يكون الخطأ مؤقتًا على الأرجح (مهلات، إعادة ضبط اتصال، upstream 502/503) وحدد عدد محاولات محدودًا مع تزايد بسيط في الفاصل. للإجراءات غير القابلة للتكرار، اشترط مفتاح عدم التكرار (idempotency key) أو فحص الحالة، وإلا قد تُسبب المحاولة تكرارات عندما تكون المحاولة الأولى قد نجحت فعلاً.

كيف تساعد معرفات التتبع في الحوادث الحقيقية، وأين يجب أن تظهر؟

اعرض معرف التتبع للمستخدم (كي يرسله للدعم) وسجّله دائمًا على الخادم مع الكود والتفاصيل الأساسية. هذا يمكّنك من تتبع فشل واحد عبر الخدمات والعميلات؛ في مشاريع AppMaster، يساعد توحيد هذا الشكل في مكان واحد على مزامنة سلوك الباك إند والويب والهواتف.

من السهل أن تبدأ
أنشئ شيئًا رائعًا

تجربة مع AppMaster مع خطة مجانية.
عندما تكون جاهزًا ، يمكنك اختيار الاشتراك المناسب.

البدء