شرح رموز حالة HTTP

الخلاصة: ستة عيوب في رموز الحالة أو الترويسات (R1 وR2 وR4 وR6 وR7 وR8)، وثلاث استجابات صحيحة (R3 وR5 وR9)، ورمزان من البوابة صحيحان لكنهما يشيران إلى مشكلة خلفها (R10 للتحقيق، وR11 عيب). وفيما يلي التفاصيل صفاً صفاً، والنتيجة المتوقعة في كل منها مأخوذة من الاصطلاحات.

R1 — عيب (C1). النتيجة المتوقعة: 201 Created مع Location: /api/v2/orders/58213. فالرمز 200 يقول «نجح الأمر» فقط، ولا يقول إن مورداً جديداً قد أُنشئ، والتطبيق الذي يتحقق من 201، أو يقرأ ترويسة Location ليفتح الطلبية الجديدة، لا يستطيع الاعتماد على هذه الاستجابة.

R2 — عيب (C2). الجسم قابل للتحليل، والقيمة 0 تخالف قاعدة «1 أو أكثر»، لذا فالنتيجة المتوقعة 422 مع خطأ JSON يسمّي الحقل quantity. والرمز 500 هو الإخفاق (Failure)، والعيب الذي خلفه غياب التحقق من المدخلات: فقد وصلت القيمة إلى شيفرة لم تستطع التعامل معها، و500 ليس أبداً الجواب الصحيح للمدخلات السيئة. ولأن 0 و1 هما القيمتان الحدّيتان لهذه القاعدة، تأكد أن القيمة 1 مقبولة، وجرّب أيضاً -1 و1.5 و"two" وغياب الكمية، لتعرف إلى أي مدى يمتد غياب التحقق.

R3 — صحيح (C2). الجسم الذي يتعذّر تحليله يحصل على 400 مع جسم خطأ JSON. أما 422 فخطأ هنا، لأنه لم يُقرأ شيء يمكن التحقق من قيمه.

R4 — عيب (C3). غياب رمز الوصول يعني «غير مصادَق»، فالنتيجة المتوقعة 401 Unauthorized مع WWW-Authenticate: Bearer، ويوجب RFC 9110 هذه الترويسة في كل استجابة 401. أما 403 فيقول للتطبيق «أنت مسجّل الدخول، لكن هذا غير مسموح لك»، فيعرض خطأ صلاحيات بدلاً من أن يرسل العميل إلى شاشة تسجيل الدخول. أعد الاختبار برمز وصول منتهي الصلاحية أيضاً لأن C3 تشمل الحالتين، واحتفظ بفحص يؤكد أن 403 ما زال يظهر في موضعه: رمز وصول صالح يُستخدم لإجراء غير مسموح له.

R5 — صحيح (C4). الطلبية موجودة لكنها تخص العميل B. وقد اختار الفريق 404 كي لا تكشف الواجهة أرقام الطلبيات الموجودة، وهو استخدام لـ 404 يذكره الدليل (حين يفضّل الخادم عدم الإفصاح عن وجود المورد). ولو أعادت الواجهة 403 هنا لكان ذلك عيباً مخالفاً لـ C4، لأنه يؤكد أن الطلبية 58101 موجودة. والفحص المهم هو المقارنة: يجب أن تتطابق الحالة والترويسات والجسم مع ما يُعاد للطلبية غير الموجودة 99999999، وهي متطابقة.

R6 — عيب (C5 وC8). النتيجة المتوقعة: 409 Conflict مع جسم خطأ JSON، لأن الإلغاء يتعارض مع حالة الطلبية الراهنة (شُحنت بالفعل). والرمز 200 مع "status":"error" يخفي الفشل: فقد يخبر التطبيقُ العميلَ أن طلبيته أُلغيت، وتحسب المراقبة الاستدعاء نجاحاً. وتحقّق كذلك من الآثار الجانبية: يجب أن تبقى حالة الطلبية «شُحنت»، وألا يكون قد بدأ أي استرداد للمبلغ.

R7 — عيب (C6). الرمز 429 صحيح عند الطلب الحادي والستين، لكن ترويسة Retry-After التي تشترطها C6 مفقودة، فلا يعرف التطبيق متى يعيد المحاولة: إما أن يرسل مزيداً من الطلبات فتُرفض بـ 429، وإما أن ينتظر أكثر من اللازم. وافحص الحدّ أيضاً: يجب أن ينجح الطلب الستون في الدقيقة نفسها.

R8 — عيب (C7). النتيجة المتوقعة: 308 Permanent Redirect مع Location: /api/v2/orders. فمع 301 يجوز لعميل HTTP أن يغيّر POST إلى GET (يسمح RFC 9110 بذلك لأسباب تاريخية)، وهذا ما حدث بالضبط: لم تصل السلة إلى /v2، ولم تُنشأ أي طلبية، وآخر استجابة في السلسلة 200، فقد يعرض التطبيق نجاحاً. ونصيحة الدليل أن تفضّل 308 على 301 في واجهات API. واسأل أي إصدارات التطبيق ما زالت تستدعي /v1، فالجواب يحدد مدى الاستعجال.

R9 — صحيح. الرمز 304 ليس خطأ: لم تتغير الطلبية منذ خزّنها التطبيق مع وسم ETag "a7f3"، فلم يرسل الخادم جسماً، ويعرض التطبيق نسخته المخزّنة. واختبر الحالة المعاكسة أيضاً: بعد أن تتغير الطلبية (بعد إلغائها مثلاً) يجب أن يعيد الطلب نفسه 200 مع الجسم الجديد ووسم ETag جديد، وإلا رأى العملاء حالة قديمة.

R10 — ليس عيباً في رمز الحالة، بل سؤال للتحقيق. يعني 502 أن موزّع الحمل تلقّى من التطبيق استجابة غير صالحة أو لم يتلقَّ استجابة أصلاً، وهذا يتفق مع إعادة تشغيل خادم التطبيق أثناء النشر في الساعة ⁦14:02⁩. سجّل الوقت والبناء والطلب، وأعد الاختبار بعد انتهاء النشر. فإن ظهر 502 خارج أوقات النشر فهو يدل على انهيار التطبيق أو قطعه الاتصالات، فأبلغ عنه مع سجلات التطبيق. وسؤالان للفريق: هل ينبغي أن يتوقف موزّع الحمل عن إرسال الطلبات إلى الخادم قبل إعادة تشغيله أثناء النشر، حتى لا يرى أي عميل HTTP الرمز 502؟ وهل يتعامل التطبيق مع صفحة خطأ HTML حيث تعد C2 بجسم JSON؟

R11 — الرمز 504 نفسه صحيح: انتظر موزّع الحمل 30 ثانية ولم يُجب التطبيق في الوقت المحدد. أما العيب فخلفه: البحث في سجل طويل (من 2019 إلى 2026) لا ينتهي خلال الثلاثين ثانية التي تسمح بها البوابة. ضيّق النطاق الزمني لتعرف تقريباً من أين يبدأ الإخفاق، وسجّل أزمنة الاستجابة، وأبلغ عنه عيباً في الأداء. واسأل مالك المنتج هل يوجد حد أقصى للنطاق الزمني: فإن وُجد، فالنطاق الذي لن تخدمه الواجهة ينبغي أن يُرفض بـ 422 (C2) بدلاً من أن تنتهي مهلته. ولن تفيد إعادة الطلب نفسه.

سؤال المطوّر: ليس آمناً بصيغته الحالية. لا تُعَد المحاولة تلقائياً إلا إذا اجتمع شرطان: أن يكون الرمز مؤقتاً (502 أو 503 أو 504)، وأن تكون الطريقة متكافئة (idempotent) مثل GET وPUT وDELETE. ولا يجوز إعادة R2 لسببين: الرمز 500 فيه ناتج عن الطلب نفسه، فيعود كما هو في كل مرة؛ وPOST ليست متكافئة، وهذا هو الخطر الأكبر: فإذا حصل POST /v2/orders على 502 أو 504 فربما أنشأ الخادم الطلبية قبل أن تضيع الاستجابة، وقد تُنشئ إعادة المحاولة التلقائية طلبية ثانية. لذلك ينبغي أن يتحقق التطبيق بعد POST فاشل من قائمة الطلبيات بطلب GET قبل أن يعرض إعادة الإرسال، وأن يوضح المطوّرون كيف تمنع الواجهة الطلبيات المكررة. أما R10 فإعادته آمنة (GET، ورمز مؤقت، مع تراجع تدريجي). وR11 طلب GET أيضاً، لكن تكرار طلب أثقل من اللازم لا يضيف إلا حملاً ثم تنتهي مهلته مجدداً، فاجعل عدد المحاولات صغيراً واستخدم التراجع التدريجي. وأخيراً، 429 من فئة 4xx ويجوز إعادة إرساله، لكن بعد مدة Retry-After فقط، وهذا سبب آخر لأهمية R7.

أبلغ عن R8 أولاً. مثال للعنوان: «POST /v1/orders يعيد 301 بدلاً من 308، فيعيد عميل HTTP إرساله بطريقة GET ولا تُنشأ أي طلبية». وهو الأول لأن العملاء على أي تطبيق ما زال يستدعي /v1 يخسرون طلبياتهم دون أي رسالة خطأ، وتنتهي السلسلة بـ 200. ثم R6 (إلغاء فاشل يُعرض نجاحاً) وR4 (غياب رمز الوصول يُعرض مشكلةَ صلاحيات، فلا يرسل التطبيق العميل إلى تسجيل الدخول). وإن قدّمت R6 لأنك تعرف أن كل التطبيقات انتقلت إلى /v2 فهذا سبب وجيه؛ المهم أن تأتي الأولوية من الأثر على العملاء. وبعد الإصلاحات، أعد تنفيذ الصفوف نفسها اختباراتِ تأكيد (Confirmation testing).

لتتحقق من عملك: يجب أن يكون لكل صف الرمز المتوقع، ومعه الترويسة حين تشترطها الاصطلاحات (Location وWWW-Authenticate وRetry-After). وإن صنّفت R3 أو R5 أو R9 عيباً، فأعد قراءة ما يقوله الدليل عن 400 مقابل 422، وعن 404 (قد يفضّل الخادم عدم الإفصاح عن وجود المورد)، وعن 304 (ليس خطأ).