التمييز بين الوصف والتنفيذ
ثبت إصدار مواصفات تدعمه الأدوات. صف المعلمات والمحتوى والاستجابات ومتطلبات الأمان. يبقى التطبيق والبوابة مسؤولين عن فرض المتطلبات المعلنة.
| العنصر | ما يصفه | فحص إضافي |
|---|---|---|
| المخطط | البنية والقيود | التحقق الفعلي وقواعد العمل. |
| استجابة موثقة | الحالة والمحتوى المتوقعان | مطابقة الاستجابات الفعلية. |
| متطلب أمني | الآلية والحقوق المعلنة | تحكم فعلي لكل عملية. |
| مثال | حالة توضيحية واحدة | الاتساق وغياب الأسرار والحالات الحدية. |
المراجعة قبل المشاركة
- افحص الحقول المطلوبة والأنواع والمديات وترقيم الصفحات والأخطاء والصيغ. استخدم أمثلة افتراضية متوافقة مع المخطط دون أسرار أو بيانات عملاء.
- قارن الوصف بالطلبات والاستجابات في بيئة مضبوطة. اختبر غياب بيانات الدخول ونقص الصلاحيات والفصل بين الحسابات.
- راجع المراجع الخارجية والأدوات التي تعالجها. نقح الوصف العام واحم البيئات والعمليات الخاصة.
صيانة التوثيق
راجع الفروق وعين مسؤولا. قد يكون المثال أو العميل المولد صحيح البنية لكنه يتجاهل قاعدة عمل. تحتاج وحدات التجربة التفاعلية إلى بيئة مناسبة وصلاحيات محدودة وبيان واضح للعمليات التي تغير الحالة.
المراجع الأساسية
مقارنة OpenAPI بالخدمة قيد التشغيل.
يتضمن وصف OpenAPI المفيد استجابات الفشل، والمخططات، والأمثلة التي يواجهها العملاء فعليًا. عندما يختلف المستند عن واجهة برمجة التطبيقات، قد ينجح التكامل في العرض التوضيحي ويفشل في بيئة الإنتاج.
- مقارنة حالات النجاح والفشل بالوصف.
- توثيق القيم الاختيارية، والترقيم، وحدود العمليات.
- اختبار عميل نموذجي قبل تغيير العقد.
المصدر الأساسي: IETF RFC 9457 — Problem Details for HTTP APIs. المنهج المرتبط: اقرأ الدليل العملي.
ZIP وTAR: الاستخراج ضمن حدود المجلد والموارد
فحص المسارات والروابط والبيانات المفكوكة قبل نشر الملفات المستخرجة.
- استخرج إلى مجلد جديد غير عام بصلاحيات دنيا. ارفض المسارات المطلقة والخروج للأعلى والروابط والملفات الخاصة غير اللازمة. افحص الوجهات المحلولة والتعارضات وفق نظام الهدف بما فيها حالة الأحرف. بادئة نصية لا تثبت الاحتواء.
- ضع حدوداً لكل ملف وللمجموع على البايتات المكتوبة وعدد الإدخالات والعمق والوقت وموارد العملية. لا تعتمد فقط على الحجم المضغوط أو المعلن. ارفض الأرشيفات المتداخلة غير اللازمة أو شارك ميزانية عامة بين المستويات. حدّث المكتبة والمرشحات.
- اختبر ../ ومساراً مطلقاً ورابطاً وتكراراً وتجاوز الميزانية. يجب أن يبقى الناتج غير منشور عند الفشل وألا يستبدل ملفات موجودة. افحص الأنواع والمحتوى قبل النشر وتحقق من الوجهة عند تنظيف المجلد.
حالة قبول قابلة للتكرار
مثال افتراضي: البيانات لا تصف عميلاً أو نتيجة مرصودة.
عرض بيانات الحالة
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}القرار المتوقع
مثال افتراضي: 2 ميغابايت مضغوطة تنتج 600 ميغابايت بميزانية 100. توقف عند تجاوز البايتات المكتوبة وأبق الدفعة غير منشورة حتى لو بدت الملفات الأولى سليمة.
Python — tarfile extraction filters and further verification
هل أرشيف صغير أو مرشح يضمن السلامة؟
لا. قد يتوسع كثيراً. أضف حدود موارد وقواعد مسارات وفحص الملفات الناتجة.
المصدر الأساسي: Python — tarfile extraction filters and further verification. المنهج المرتبط: اقرأ الدليل العملي.
أخطاء API: الأنواع والحالات والأدلة
الملاحظات المرجعية المفصّلة متاحة باللغة الإنجليزية في هذه النسخة.
Include errors in contract tests
A new type URI, removed extension or changed status may alter consumer behaviour. Failure examples are part of the contract alongside successful responses.
- Replay existing clients against representative refusals.
- Check tolerance of unknown extensions and localised text.
- Document migration of a problem identity and actually observed use.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5