توحيد هيكل استجابات النجاح والأخطاء بصيغة JSON | بناء نقاط نهاية JSON API في PHP وقراءة php://input ورموز حالة HTTP

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

وحّد المفاتيح العليا للاستجابة مثل {"ok": bool, "data": mixed, "error": ?string, "errors": array}.
أنشئ دالة مساعدة موحدة jsonResponse(array $payload, int $status = 200) لإرسال الرأس ورمز الحالة والـ JSON معاً.
لا تكشف أبداً نصوص استعلامات SQL أو مسارات ملفات الخادم الداخلية ضمن رسائل الخطأ المرسلة للعميل في بيئة الإنتاج.

تشترك استجابتا النجاح والفشل في نفس المفاتيح العليا تماماً (ok وdata وerror)، مما يمنع أخطاء الخصائص غير المعرفة في الواجهة.

مخطط تدفق التنفيذ العملي لقسم توحيد هيكل استجابات النجاح والأخطاء بصيغة JSON في لغة PHP

PHP

<?php
function buildApiEnvelope(bool $ok, mixed $data = null, ?string $err = null): string {
    return json_encode([
        'ok'    => $ok,
        'data'  => $data,
        'error' => $err,
    ], JSON_UNESCAPED_UNICODE);
}

echo buildApiEnvelope(true, ['user_id' => 12]) . "\n";
echo buildApiEnvelope(false, null, 'Unauthorized token') . "\n";

Structuring Consistent JSON Payloads توحيد هيكل استجابات النجاح والأخطاء بصيغة JSON

شرح صفوف ومحتوى الفقرة

جميع فقرات هذا الدرس (بناء نقاط نهاية JSON API في PHP وقراءة php://input ورموز حالة HTTP)