Jenkins / أسس التنفيذ والمصدر / الدرس 2

بنية Declarative وعقود الخطوات

اقرأ pipeline وagent والمراحل والخطوات وpost كتعريف تنفيذ منظم.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى 2026-10-28

في هذه الصفحة

أهداف الدرس

تمييز الصياغة المنظمة عن Groovy الحر.
شرح تخصيص وكيل المرحلة ونطاق post.

Jenkinsfile شيفرة تسليم تنفيذية

تقدم Declarative Pipeline نموذجاً منظماً فوق أنظمة Pipeline وقواعد Groovy. يحتوي pipeline أقساماً وتوجيهات مدعومة لا أي تسلسل اعتباطي من العبارات. تمثل Scripted Pipeline نموذجاً آخر، ويتيح script منفذاً مقصوداً داخل خطوات Declarative. اختر الشكل الأبسط الذي يوضح العمل. تستخدم أمثلة Parcel بنية منظمة قصيرة وتبقي تحويلات العمل في برامج عادية قابلة للاختبار بدلاً من تضخيم نص التنسيق. لا يعني وجود أقواس Groovy أن كل تركيب لغة مقبول في كل موضع من هذا النموذج.

حدد موضع طلب السعة

يبقى التعريف التالي، رغم اكتمال شكله، نص دورة غير قابل للتشغيل؛ لا يُحفظ Jenkinsfile ولا يُرسل إلى متحكم. تتجنب agent none تخصيص منفذ عام، وتطلب المرحلة وسماً افتراضياً. تحتاج الحقيقة إضافات Pipeline المناسبة ووكيلًا مؤهلاً مصرحاً به. ينتج echo سطر سجل فقط ولا يجمع Parcel أو يختبره أو يحفظه أو يصدره. يهدف المثال إلى إظهار البنية والمتطلبات دون اختلاق تشغيل ناجح. لا يجعل post النتيجة الأصلية ناجحة لمجرد أن خطوة الإبلاغ نفذت.

groovy هيكل Declarative توضيحي

pipeline {
    agent none
    stages {
        stage("Review fixture") {
            agent { label "parcel-lab" }
            steps {
                echo "Synthetic fixture review"
            }
            post {
                always { echo "Stage observation finished" }
            }
        }
    }
}

الوسم تعليمي لا وكيل مضبوط. يخص post هذه المرحلة ولا يجعل always إخفاق السابق ناجحاً. لم يعمل مدقق صياغة Jenkins أو محركه.

تنظم الأسماء الأدلة ولا تعزل

تحدد المرحلة جزءاً ذا معنى وتساعد عرض النتيجة، لكن اسمها لا يختار عقدة جديدة ولا ينظف مجلداً. يحدد موضع agent نطاق التخصيص. قد تتشارك مراحل تخصيصاً وملفات، وتحتاج المراحل ذات الوكلاء المختلفين نقلاً صريحاً. حدد دليل كل مرحلة وما يحتاجه التالي. قد يحسن تقسيم نص صدفة إلى أسماء مراحل التنقل دون تغيير العملية والثقة ودورة الناتج. لذلك يجب أن تشرح المراجعة ما تغيّر فعلاً في الحدود، لا عدد الأعمدة الجديدة التي ظهرت في الواجهة.

احفظ نتائج post منفصلة

يراقب post على مستوى السير أو المرحلة نطاق اكتماله. للشروط success وfailure وunstable وaborted وalways وcleanup معانٍ وترتيب موثقان. قد تفشل خطوة تقرير أو تنظيف مستقلة عن الاختبار الأصلي؛ احفظ الحقيقتين ولا تدع آخر إجراء ظاهر يعيد القصة. يعني always اختيار الشرط بغض النظر عن حالة النطاق، لا ضمان إصلاح كل فشل خارجي أو مجلد ضائع. ما زال العمل المعتمد على ملف يحتاج سياق مجلد مناسباً. تفيد معرفة النطاق عندما ينجح تقرير مرحلة بينما تبقى نتيجة السير الكلي غير ناجحة.

اجعل متطلبات الدليل صريحة

يفحص النموذج المحلي الكامل وجود كل ملاحظة مرحلة مطلوبة ونجاحها، ويرفض غياب التغليف رغم نجاح الاختبار. لا يحاكي تحليل Declarative أو نتائج Jenkins أو ترتيب post. يفصل حجمه الصغير تقرير الخطوات عن شرط الإصدار. تحتاج الحقيقة معالجة صريحة لعدم الاستقرار والفشل والإلغاء والتخطي وربط الملاحظات بالمراجعة والمرشح. لا تتبادل مرحلة طباعة ناجحة وفحص تطبيق مطلوب المعنى نفسه. يوضح المثال سبب عدم كفاية قائمة تخلو من الفشل إذا لم تنتج كل الأدلة التي نص عليها العقد.

python نمذجة أدلة مراحل مطلوبة

required = {"compile", "tests", "package"}
observed = {"compile": "success", "tests": "success"}
missing = sorted(required - observed.keys())
ready = not missing and all(observed[k] == "success" for k in required)
print(bool(ready))
print(missing)

الناتج المتوقع

False
['package']

يستخدم النموذج نتائج افتراضية بلا كائنات Jenkins. يوضح رفض الغائب لا خوارزمية نتيجة إنتاجية.

الأخطاء الشائعة وإصلاحها

توضع عبارة Groovy اعتباطية في موضع يتطلب توجيه Declarative.

لماذا يحدث؟: عوملت لغة التعريف المنظمة كما لو كانت برنامج Groovy غير مقيد.
كيف تصلحه؟: استخدم شكل التوجيه الموثق أو كتلة script صغيرة لها مبرر واضح.
كيف تتجنب تكراره؟: راجع كل تركيب ضمن نطاق Declarative الصحيح لا وفق صحة Groovy العامة فقط.

يُفترض أن إضافة مرحلة جديدة توفر آلة أو مجلداً نظيفاً.

لماذا يحدث؟: اختلط حد العرض والتنقل بحد تخصيص الوكيل ومساحة العمل.
كيف تصلحه؟: صرّح بالتخصيص ونقل البيانات بين المراحل بدلاً من استنتاجهما من الاسم.
كيف تتجنب تكراره؟: وثق المراحل التي تتشارك التنفيذ والملفات وتلك التي تحتاج نقلاً مستقلاً.

يخفي نجاح نشر تقرير post اختباراً فاشلاً في قرار الإصدار.

لماذا يحدث؟: حلت نتيجة الإبلاغ محل دليل التطبيق المطلوب.
كيف تصلحه؟: احفظ نتيجة الاختبار الأصلية وقيّم الفحوص الإلزامية صراحة قبل الترقية.
كيف تتجنب تكراره؟: افصل عقود التشخيص والتنظيف والإصدار كي لا يغير نجاح أحدها معنى الآخر.

اختبر فهمك

1. لماذا تستخدم agent none عندما تحتاج المراحل فئات عقد مختلفة؟

اعرض الحل المشروح

تتجنب بذلك احتجاز منفذ عام طوال السير، وتتيح لكل مرحلة طلب الفئة المناسبة لها. كما تظهر افتراضات التخصيص ونقل الملفات. تبقى كل عملية تعتمد على الملفات محتاجة إلى سياق تنفيذ مناسب، حتى مع عدم تخصيص وكيل عام.

2. هل يضمن post always رفع ناتج بعد اختفاء الوكيل؟