صيغة موحدة للأخطاء

جزء من قسم واجهات REST API في رحلة Node.js على Coddy. الدرس 12 من 25.

تُرجع واجهة API لديك الأخطاء الآن بصيغتين: سلسلة نصية لخطأ 404 وكائن zod لخطأ 400. يجب على العميل التعامل مع كل صيغة منهما. اختر صيغة واحدة لكل خطأ:

{ "error": { "code": "not_found", "message": "Invoice not found" } }

{ "error": { "code": "invalid_body", "message": "Too small: ...",
             "fields": { "amount": ["Too small: expected number to be >0"] } } }

يُستخدم code للبرامج: فهو لا يتغير أبدًا، لذا يمكن للعميل مقارنته. أما message فهو للناس، وقد تتغير صياغته. ويحدد fields للحقل أي مُدخل ينبغي تمييزه. اكتب الصيغة في دالة واحدة واستدعها من كل مسار، حتى لا تختلف أي مسارات:

sendError(res, 404, 'not_found', 'Invoice not found');

التحدي

سهل

ترسل واجهة API الآن الأخطاء بصيغتين: سلسلة نصية عادية لخطأ 404، وكائن zod لخطأ 400. اجعل لجميع الأخطاء الصيغة نفسها، حتى يتمكن العميل من قراءتها كلها بالطريقة نفسها. من الآن فصاعدًا، سيبدو كل خطأ هكذا، مع إضافة fields فقط عند وجود شيء لإدراجه:

{ "error": { "code": "not_found", "message": "Task not found" } }

في errors.js، أكمل sendError(res, status, code, message, fields). تستجيب الدالة بالحالة المحددة وبالصيغة أعلاه. أضف fields إلى الكائن الداخلي فقط عند تقديم هذه الوسيطة. الدالة sendInvalid الموجودة أسفلها مكتوبة بالفعل، وهي تستدعي دالتك.
في routes/tasks.js، استورد الدالتين المساعدتين:
- استبدل استجابات 404 الأربع (GET وPATCH وPUT وDELETE لمهمة واحدة) بـ sendError، باستخدام الرمز not_found والرسالة Task not found.
- استبدل استجابات 400 الثلاث الخاصة بجسم طلب غير صالح (POST وPATCH وPUT) بـ sendInvalid(res, result.error).
عندئذٍ سيبدو جسم الطلب غير الصالح هكذا (تكتب zod الرسالة):
```
{
  "error": {
    "code": "invalid_body",
    "message": "Invalid input: expected string, received number",
    "fields": { "title": ["Invalid input: expected string, received number"] }
  }
}
```
في server.js، استورد sendError واستخدمها في معالج الأخطاء أسفل الملف:
- يُرجع جسم الطلب الذي ليس JSON صالحًا الحالة 400، والرمز invalid_json، والرسالة The body is not valid JSON.
- أي خطأ آخر يُرجع الحالة 500، والرمز server_error، والرسالة Something went wrong.

جرّب ذلك: يعيد DELETE /api/tasks/99 الحالة 404 مع { "error": { "code": "not_found", "message": "Task not found" } }، ومن دون fields. أرسل POST مع { "title": 123 } إلى /api/tasks: ستحصل على الحالة 400 مع خطأ invalid_body أعلاه. يرفض شريط الطلبات إرسال JSON غير صالح، لذا تختبر عمليات التحقق حالة invalid_json نيابةً عنك.

جرّب بنفسك

import { z } from 'zod';

// يرسل كل خطأ بصيغة موحّدة:
// { "error": { "code": "not_found", "message": "Task not found" } }
// مع إضافة "fields" فقط عند تقديمها.
export const sendError = (res, status, code, message, fields) => {
    // أرسل الإجابة هنا
};

// خطأ zod بوصفه 400: مشكلته الأولى هي الرسالة، ومشكلات كل حقل
// في fields.
export const sendInvalid = (res, zodError) =>
    sendError(res, 400, 'invalid_body', zodError.issues[0].message, z.flattenError(zodError).fieldErrors);