كيف تصمّم استجابات خطأ متّسقة وتُبلِغ عن أخطاء الـ validation؟

Question

IT Interview Practice · Accepted Answer

تفعل استجابة الخطأ الجيدة أمرين: تستخدم **الـ HTTP status code الصحيح** (الإشارة المقروءة آليًّا)، وتُرجع **جسمًا مُهيكلًا متّسقًا** يستطيع المطوّر التصرّف بناءً عليه. أشكال الأخطاء غير المتّسقة من أكبر مصادر المعاناة في جانب العميل.

## استخدم صيغة خطأ قياسية: RFC 7807 (problem+json)

يعرّف RFC 7807 جسم "problem details" قياسيًّا بـ media type مخصّص، بحيث يبدو كل خطأ عبر الـ API متماثلًا:

```http
HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No user exists with id 999",
  "instance": "/users/999"
}
```

- `type` — URI يعرّف فئة الخطأ (قابل لفكّ المرجع نحو التوثيق).
- `title` — ملخّص قصير مقروء للبشر (مستقر لكل `type`).
- `status` — الـ HTTP status، مُكرَّر للتيسير.
- `detail` — تفسير محدّد لـ *هذه* الحالة.
- `instance` — أيّ طلب/مورد وقع عليه.

## أخطاء الـ validation: أبلِغ عنها كلها دفعة واحدة

للتحقق من نماذج/حقول، أرجِع `422` (أو `400`) و**مصفوفة أخطاء حقول** ليستطيع العميل إبراز كل حقل خاطئ في تمريرة واحدة — لا خطأً في كل مرة:

```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    { "field": "email", "code": "invalid_format", "message": "must be a valid email" },
    { "field": "age",   "code": "out_of_range",   "message": "must be >= 18" }
  ]
}
```

## المبادئ

```text
✓ Same body shape for every error (one code path on the client)
✓ A stable machine-readable code (type/code) — clients branch on this, not on prose
✓ Human-readable message for developers/logs
✗ Never leak stack traces, SQL, or internal paths to clients
```

## لماذا يهم

تصميم الأخطاء هو حيث تنجح الواجهات أو تفشل بهدوء في العالم الحقيقي: المسار السعيد سهل، لكن المستهلكين يقضون معظم وقت التنقيح في مسار الخطأ، وعقد خطأ غير متّسق أو غامض يجعل التكامل بائسًا. يستخدم المُقابِلون هذا للتحقق من أمرين. أولًا، **status code وجسم مُهيكل يعملان معًا** — الـ status إشارة خشنة للأدوات وإعادة المحاولة، والجسم يحمل التفصيل القابل للتنفيذ — لا النمط المضادّ `200 OK` بخطأ في داخله. ثانيًا، **رمز خطأ مستقر مقروء آليًّا** (عبر `type` في RFC 7807 أو حقل `code`) ليتفرّع العميل على `"insufficient_funds"` بدل مطابقة سلسلة رسالة إنجليزية قد يُعاد صوغها أو تُترجَم محلّيًّا. إرجاع كل أخطاء الـ validation دفعة واحدة، وعدم تسريب تفاصيل داخلية كالـ stack traces أبدًا، يُكمِل إجابةً تُظهر أنك بنيت واجهات اضطرّت فرق أخرى لاستهلاكها فعلًا.

استخدم صيغة خطأ قياسية: RFC 7807 (problem+json)

أخطاء الـ validation: أبلِغ عنها كلها دفعة واحدة

المبادئ

لماذا يهم

أسئلة ذات صلة