التقييم من منظور العميل
الجدول إطار للمراجعة وليس ضمانا عاما. قد يؤثر حقل إضافي في قارئ صارم، وقد تكسر قيمة تعداد جديدة معالجة تفترض حصر القيم. احصر التطبيقات والمكتبات والافتراضات.
| التغيير | الخطر المطلوب فحصه | الدليل اللازم |
|---|---|---|
| حذف حقل أو تغيير اسمه | تعذر القراءة | انتقال صريح واختبارات عملاء. |
| إضافة حقل اختياري | قارئ صارم أو تعارض أسماء | اختبار المستهلكين الحاليين. |
| إضافة قيمة في الاستجابة | معالجة حالات غير مكتملة | سلوك واضح للقيم المجهولة. |
| تغيير قيمة افتراضية | نتيجة عمل مختلفة | مقارنة الحالات دون قيمة صريحة. |
تنظيم التعايش
- صف البنى القديمة والجديدة والقيم الافتراضية والأخطاء وترقيم الصفحات والصلاحيات. نفذ اختبارات عقد بحالات ممثلة للعملاء.
- اختر طريقة صريحة لتحديد الإصدار. ميز إصدار الخدمة عن إصدار مستند OpenAPI وافحص التخزين المؤقت والبوابات.
- انشر جدولا ودليل انتقال ووسيلة اتصال. تابع الاستخدام الفعلي بقياس متناسب، وخطط لتراجع متوافق مع البيانات.
التمييز بين الإهمال والإيقاف
يشير Deprecation إلى مورد مهمل، ويمكن لـ Sunset إعلان وقت توقع عدم توافره. لا تنقل هذه الترويسات التطبيقات تلقائيا. راجع المستهلكين الباقين والالتزامات والاستعادة قبل إيقاف إصدار.
المراجع الأساسية
- Google AIP-180 — Backwards compatibility [EN]
- IETF RFC 9745 — Deprecation [EN]
- IETF RFC 8594 — Sunset [EN]
تأثير الإصدار على المستخدم
إضافة رقم إلى عنوان URL لا يحافظ على العملاء الحاليين. قد يكون تغيير النوع أو القيمة المتوقعة أو السلوك أو استجابة الخطأ غير متوافق حتى مع بقاء المسار كما هو.
- جرد العملاء النشطين والاستخدام المُلاحَظ.
- اختبار إصدارات العميل القديمة مقابل العقد الجديد.
- نشر فترة تعايش وفحص الاستخدام قبل الإيقاف.
المصدر الأساسي: IETF RFC 9457 — Problem Details for HTTP APIs. المنهج المرتبط: اقرأ الدليل العملي.
مهام API غير المتزامنة
قبول الطلب لا يثبت اكتمال العمل.
- الحساب والعملية ومعرّف قابل لإعادة الاستخدام
- الحالة والوقت والفاصل والانتهاء
- الناتج والخطأ والإلغاء والآثار الباقية
- مهمة واحدة مأذونة ونتيجة متحققة بعد الانقطاع
حالة قبول قابلة للتكرار
مثال افتراضي: البيانات لا تصف عميلاً أو نتيجة مرصودة.
عرض بيانات الحالة
{
"job_id": "J-42",
"timeline": [
{
"elapsed_seconds": 0,
"http": 202,
"state": "pending"
},
{
"elapsed_seconds": 5,
"http": 200,
"state": "running"
},
{
"elapsed_seconds": 6,
"http": 200,
"state": "cancel_requested"
},
{
"elapsed_seconds": 7,
"http": 200,
"state": "succeeded"
}
]
}القرار المتوقع
الرد 200 عند قراءة الحالة لا يعني اكتمال المعالجة. بعد طلب الإلغاء، يعتمد الاستنتاج على النتيجة المؤكدة فقط.
طلب الإلغاء وصل متأخرًا
سيناريو افتراضي: المهمة نفسها J-42، والزمن بالثواني منذ الإرسال. أسماء الحالات يحددها عقد هذا المثال ولا يفرضها HTTP.
| الوقت | الرد والحالة | الاستنتاج المثبت |
|---|---|---|
| +0 s | HTTP 202 · pending | قُبلت للمعالجة؛ لم تتأكد النتيجة النهائية. |
| +5 s | HTTP 200 · running | نجحت قراءة الحالة؛ المهمة ما زالت تعمل. |
| +6 s | HTTP 200 · cancel_requested | سُجل طلب التوقف؛ الإلغاء لم يتأكد بعد. |
| +7 s | HTTP 200 · succeeded | اكتملت المعالجة قبل الإلغاء. اعرض النجاح المؤكد وتحقق من الآثار؛ لا تعلن إلغاء المهمة. |
هل 202 يثبت أن العمل سيكتمل؟
لا. يؤكد القبول للمعالجة وليس النتيجة النهائية. افحص حالة العملية.
المصدر الأساسي: MDN — 202 Accepted. المنهج المرتبط: اقرأ الدليل العملي.
تحديثات البرامج: التحقق من تغيير هوية الموقّع
تحديد ما إذا كان المنتج الموقّع يطابق المنتج وعملية البناء والإصدار المعتمدين.
- قبل فحص الحزمة سجّل المنتج والمفتاح أو هوية الشهادة والجهة المصدرة وعملية البناء المسموحة. اربط التوقعات بالبرنامج وبقناة تأكيد موثوقة مسبقاً. لا تجعل المنتج وحده يحدد سياسة قبوله.
- طابق بصمة الملف المستلم مع موضوع إفادة المصدر. تحقّق من التوقيع بجذور الثقة المقصودة ثم الهوية والباني والمعلمات. توقيع صحيح تشفيرياً من هوية أخرى لا يحقق سياسة الخدمة.
- اختبر تدويراً معلناً وجهة إصدار غير متوقعة وتوقيعاً غائباً وملفاً مختلفاً. أبقِ المنتج معلقاً إن لم تتأكد الهوية الجديدة. سجّل الاعتماد والرجوع؛ التوقيع لا يثبت غياب الثغرات.
حالة قبول قابلة للتكرار
مثال افتراضي: البيانات لا تصف عميلاً أو نتيجة مرصودة.
عرض بيانات الحالة
{
"signature_valid": true,
"digest_matches": true,
"expected_signer": "approved-publisher",
"observed_signer": "different-publisher",
"expected": "hold_for_independent_confirmation"
}القرار المتوقع
مثال افتراضي: البصمة مطابقة والتوقيع صحيح لكن الموقّع ليس المعتمد. يبقى التثبيت معلقاً حتى تأكيد التغيير عبر مصدر مستقل.
المصدر الأساسي: SLSA v1.2 — Verifying artifacts. المنهج المرتبط: اقرأ الدليل العملي.
API: الإهمال والإيقاف
الملاحظات المرجعية المفصّلة متاحة باللغة الإنجليزية في هذه النسخة.
Plan retirement beyond the version number
A published version does not say when consumers need to migrate. Connect deprecation announcements, retirement dates and existing-client tests.
- Distinguish Deprecation, Sunset and policy links.
- Check that Sunset does not precede Deprecation when both dates are provided.
- Measure remaining consumers and validate the replacement before cutover.
Compare deprecation and retirement announcements →
IETF · RFC 9745 · Deprecation · Standards Track · March 2025 · §2–5 · consulted 2026-10-23
IETF · RFC 8594 · Sunset · Informational · May 2019 · §3–5, §8 · consulted 2026-10-23