فصل الحالة والنوع والواقعة
يحدد RFC 9457 صيغة application/problem+json. استخدم نوع مشكلة ثابتا وتفصيلا مفهوما للواقعة؛ لا تجعل العميل يحلل نصا مترجما لاتخاذ القرار. إن وجد status فليتطابق مع حالة HTTP الفعلية.
| الحالة | معنى HTTP | التعامل المقترح |
|---|---|---|
| 400 | طلب غير صحيح | التصحيح قبل التكرار. |
| 401 | غياب بيانات مصادقة صالحة | فحص البيانات والآلية الموثقة. |
| 403 | الطلب مفهوم لكنه مرفوض | مراجعة الحقوق؛ التكرار لا يمنحها. |
| 503 | الخدمة غير متاحة مؤقتا | انتظار ومحاولات محدودة إذا سمحت العملية. |
توقع مسارات الفشل
- وثق الرموز والصيغ والتعامل المتوقع. اختبر الاستجابة الفارغة ومحتوى البوابة غير JSON وانقطاع الاتصال وانتهاء المهلة.
- تحقق من المدخلات والصلاحيات على الخادم. عالج الأخطاء المتوقعة دون إخفاء أعطال مجهولة، ولا تقدم فشل العمل باعتباره نجاحا.
- أرجع معرف ترابط مفيدا للدعم. أبق تتبع المكدس والاستعلامات الداخلية وكلمات المرور والرموز خارج الاستجابة العامة.
التكرار عند وجود مبرر
لا تسمح 5xx بمحاولات غير محدودة. اجمع العقد والحالة ومنع الأثر المكرر والمهلة. أبلغ عن العيب بمثال أدنى منقح؛ وبعد الإصلاح اختبر الحالة الأصلية وحالات رفض الوصول القريبة.
المراجع الأساسية
يجب أن توجه أخطاء واجهة برمجة التطبيقات (API) الإجراءات دون تسريب.
توفر حالة HTTP فئة أولية، ولكن قد يحتاج العميل إلى نوع ثابت وتفاصيل مفيدة. يصف RFC 9457 بنية مشكلة شائعة؛ ولا يبرر ذلك كشف التتبعات الداخلية أو البيانات الحساسة.
- فصل الرفض الدائم، والمدخلات القابلة للتصحيح، والفشل المؤقت.
- توثيق النوع والحالة والإجراءات المحتملة للعميل لكل خطأ مهم.
- اختبار عدم احتواء الاستجابات على بيانات سرية أو حمولات كاملة غير ضرورية.
المصدر الأساسي: IETF RFC 9457 — Problem Details for HTTP APIs. المنهج المرتبط: اقرأ الدليل العملي.
إعادات API: احسب ميزانية الوقت كاملة
حدد سقف الاتصالات والمهلة العامة.
حالة تعليمية افتراضية: الأرقام لا تصف CIE أو عملاءها.
نموذج افتراضي: أربعة اتصالات حتى 250 ملي ثانية وانتظارات 100 و200 و400. يُستبعد التفاوت العشوائي والاتصال والطوابير والتحقق المحلي.
- المحاولات الكلية
- 41 + 3
- الانتظار الكلي (ms)
- 700100 + 200 + 400
- ميزانية النموذج (ms)
- 17004 × 250 + 700
| الخطوة | أقصى اتصال (ms) | الانتظار التالي (ms) |
|---|---|---|
| المحاولة 1 | 250 | 100 |
| المحاولة 2 | 250 | 200 |
| المحاولة 3 | 250 | 400 |
| المحاولة 4 | 250 | 0 |
| المجموع | 1000 | 700 |
- وقت الاتصالات1,000
- الانتظار المتراكم700
- المهلة العامة (ms)1,500
فحوص قبل الاستنتاج
- 1000 + 700 = 1700 تتجاوز مهلة 1500 ملي ثانية.
- مرّر المهلة العامة وامنع تكرار الأثر؛ انتهاء المهلة لا يثبت إلغاء المعالجة البعيدة.
جرّب ميزانية الإعادات
n × T + W × (2^(n−1) − 1)
المنهج المرتبط: اقرأ الدليل العملي.
أخطاء API: الأنواع والحالات والأدلة
الملاحظات المرجعية المفصّلة متاحة باللغة الإنجليزية في هذه النسخة.
Handle an error without parsing its sentence
An API client may receive a translated title, missing member or unfamiliar extension. Preserve decisions based on the documented type and HTTP status, then connect a safe action to the context.
- Compare received status and JSON status without silently replacing either.
- Test absent type, string status instead of a number, and an unknown extension.
- Separate person-facing text, business code and occurrence reference.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5