التحديث وإعادة الاستخدام

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

ما هي "الوحدة النمطية"

"الوحدة النمطية" هي في الأساس سير عمل يعلن عن حقول المستوى الأعلى لـ WorkflowModuleContract. ويكشف بالإضافة إلى ذلك:

• inputs — المعلمات التي يجب على المتصل تمريرها (مع الاسم والنوع والمطلوب والقيمة الافتراضية والوصف)
• outputs — النتيجة المنظمة التي تم إنشاؤها بعد التنفيذ (يمكن للمتصل الرجوع إليها مباشرة)
• version — رقم الإصدار الدلالي لتسهيل قفل المتصل

name: my-team-slack-notifier
version: "1.0.0"

module:
  enabled: true
  inputs:
    webhook_url:
      type: string
      required: true
      description: Slack incoming webhook URL
    channel:
      type: string
      required: false
      default: "#general"
    message:
      type: string
      required: true
    mentions:
      type: array
      items: { type: string }
      required: false
  outputs:
    message_ts:
      type: string
      description: Slack 返回的 message timestamp，可用于后续更新消息
    status:
      type: string
      enum: [sent, failed]

# 模块自己的步骤（内部细节，对调用方黑盒）
steps:
  - id: format_text
    type: code
    language: node
    code: |
      const msg = process.env.WF_VAR_MESSAGE;
      const mentions = JSON.parse(process.env.WF_VAR_MENTIONS || '[]');
      return { text: mentions.map(u => `<@${u}>`).join(' ') + ' ' + msg };

  - id: post
    type: code
    depends_on: [format_text]
    credentials: [slack_oauth]
    code: |
      // 调 Slack API，返回 message_ts / status …

بعد الحصول على العقد، ستقوم خطوة سير العمل الفرعي للمتصل (سير العمل الأصلي) بما يلي:

• التحقق الثابت عند الحفظ - لن يتم حفظ المدخلات المطلوبة إذا كان أحدها مفقودًا؛
• التحقق في وقت التشغيل - إذا كان النوع غير متطابق/التعداد غير موجود في القائمة، فسيتم الإبلاغ عن خطأ مباشرة؛
• الإكمال التلقائي في المحرر - عند كتابة المدخلات: يمكنك التمرير لأسفل لمعرفة الحقول التي تعرضها الوحدة.

كيف يستدعي سير العمل الأصل الوحدة النمطية

steps:
  - id: build_report
    type: code
    # ...

  - id: notify
    type: sub_workflow
    module: my-team-slack-notifier    # 引用我们上面定义的模块
    version: "^1.0.0"                  # 锁主版本
    inputs:
      webhook_url: "{{credentials.slack_webhook}}"
      channel: "#ops-alerts"
      message: "日报已生成：{{steps.build_report.data.summary}}"
      mentions: ["U1234", "U5678"]

  - id: record
    type: code
    depends_on: [notify]
    code: |
      const ts = process.env.STEP_OUTPUT_NOTIFY_MESSAGE_TS;
      // 把 ts 存到你自己的数据库，方便后续更新那条消息 ...

النقاط الرئيسية:

• module: dingyue-module-slack-deliver إنه معرف الوحدة، وسيقوم النظام الأساسي بحلها بناءً على الاسم + الإصدار.
• inputs: يتوافق مع المدخلات في عقد الوحدة.
• بعد الانتهاء من المكالمة، يمكنك المرور {{steps.deliver.outputs.message_id}} قراءة إخراج الوحدة.

تحويل سير العمل الحالي إلى وحدات نمطية: قم بالترقية إلى الوحدة النمطية

في معظم الأحيان، لن تكتب وحدة نمطية من الصفر، بل ستسحبها من سير عمل موجود. عملية:

1. افتح سير عمل حيث تعتقد أن "هذا المنطق يستحق إعادة استخدامه".
2. استخدم تحديد إطار الماوس أو Shift+click لتحديد عدة خطوات متتالية في اللوحة القماشية.
3. انقر بزر الماوس الأيمن على القائمة → "الترقية إلى الوحدة النمطية"، أو الزر الذي يحمل نفس الاسم في شريط الأدوات العلوي.
4. في النافذة المنبثقة:
   • قم بإعطاء اسم وحدة ذو معنى (فريد عالميًا، يوصى ببدءه باسم فريقك، على سبيل المثال: my-team-slack-notifier)؛
   • ستستنتج المنصة تلقائيًا المسودة الأولى للمدخلات/المخرجات بناءً على الجزء المحدد، والذي يمكنك تحريره؛
   • بعد التأكيد، انقر فوق "إنشاء وحدة".
5. سيتم استبدال هذه الخطوات في سير العمل الأصلي بعقدة سير عمل فرعية - تتم محاذاة المعلمات والاتصالات تلقائيًا.

ترقية الوحدة وتوافق الإصدار

في كل مرة تقوم فيها بحفظ وحدة، يتم إنشاء إصدار جديد. يمكن تحديد سير العمل الأصلي في خطوة سير العمل الفرعي:

• version: latest — استخدام أحدث إصدار تلقائيًا (مناسب للوحدات التي تقوم بصيانتها بنفسك)
• version: "1.2.0" — مقفل على إصدار محدد (مناسب للرجوع إلى وحدات الأشخاص الآخرين، والخوف من الترقية والإضرار بالتوافق)
• version: "^1.2.0" — السماح بترقيات الإصدار الثانوية، وحظر الإصدارات الرئيسية المشتركة بين الإصدارات

ما هو "التغيير المتوافق"؟

• ✓ أضف مدخلاً اختياريًا (لا تعتبر القيم المطلوبة/الافتراضية معطلة)
• ✓ إضافة حقل الإخراج
• ✗ حذف/إعادة تسمية الإدخال
• ✗ حذف/إعادة تسمية الإخراج
• ✗ تغيير نوع الإدخال

عند إجراء تغييرات تؤدي إلى كسر التوافق، يجب ترقية الإصدار الدلالي إلى الإصدار الرئيسي التالي. لا يتم فرض النظام الأساسي، ولكنه محمي عندما يقوم المتصل بقفل ^X.Y.Z.

كشف الحلقة

لا يمكن للوحدة A أن تشير إلى نفسها بشكل غير مباشر. تقوم المنصة بالكشف على مستويين:

1. الكشف الثابت في وقت الإصدار — عند حفظ وحدة نمطية، يقوم DFS بمسح الرسوم البيانية التبعية لجميع الوحدات الأخرى التي يشير إليها ويرفض الحفظ في حالة وجود حلقات.
2. الكشف الديناميكي في وقت التشغيل — إذا حدثت دورة تم حلها بواسطة وقت التشغيل أثناء التنفيذ (على سبيل المثال، تمت الإشارة إليها بعد فرع شرطي)، فسيتم ظهور خطأ على الفور.

الحد الأقصى الافتراضي لعمق العودية هو 8 مستويات. هذا هو عمق "ابن الأب والابن"، وليس دعوة واحدة للانقسام.

العزلة المتغيرة

تعمل الوحدة كـ "WorkflowExecutionContext التابع"، معزولة تمامًا عن السياق الأصلي:

• لا يتم توريث متغيرات/خطوات المخرجات/الوكلاء إلى الطفل افتراضيًا؛
• لن تتجاوز مخرجات الخطوة الداخلية للطفل إلى الوالد - يمكن للوالد فقط رؤية المخرجات المعلنة في العقد؛
• الطريقة الوحيدة لتمرير البيانات بين الوالدين والطفل هي المدخلات/المخرجات (عقد صريح).

هذا العزل هو حجر الزاوية في الموثوقية المعيارية - "الصندوق الأسود" ليس استعارة، بل هو حرفي.

خفض الرتبة من الوحدة: استعادة الوحدة إلى خطوة مضمنة

إذا قمت بتعديله ووجدت أن جزءًا معينًا من المنطق يُستخدم فعليًا في مكان واحد فقط، وتحويله إلى وحدة نمطية يزيد من تكلفة الفهم، فيمكنك عكس التخفيض:

1. حدد عقدة سير العمل الفرعي في سير العمل الأصلي؛
2. انقر بزر الماوس الأيمن → "تخفيض السطر"؛
3. يقوم النظام الأساسي بتوسيع خطوة الوحدة إلى سير العمل الأصلي، وتختفي عقدة سير العمل الفرعي.

لا يتم حذف الوحدة الأصلية نفسها - إذا كانت هناك مسارات عمل أخرى تشير إليها، فستظل صالحة.

حيث لإدارة جميع الوحدات

إن شريط التنقل الرئيسي "مكتبة الوحدات النمطية" الموجود على اليسار هو عرض النظرة العامة الخاص بك. هنا يمكنك:

• اطلع على قائمة بجميع الوحدات (12 وحدة مضمنة + تلك التي أنشأها فريقك)
• استعلام عكسي يعتمد على "من الذي يشير إليّ" - تحقق من الذي سيتأثر قبل تغيير الوحدة
• عرض محفوظات إصدار الوحدة النمطية/الفرق
• نشر/أرشفة/نقل الملكية

متى تصنع الوحدات

• ✓ يظهر نفس المنطق في أكثر من سيرتي عمل
• ✓ عقد خارجي مستقر منطقيًا وواضح (عادةً "إرسال الرسائل/التحقق من التقارير/إنشاء تخفيض السعر")
• ✓ تجاوز سير العمل الواحد 15 خطوة، وانخفضت إمكانية قراءته.
• ✗ يتم استخدام قطعة المنطق مرة واحدة فقط ولن يتم إعادة استخدامها في المستقبل - فهي مضمنة مباشرة
• ✗ وظيفة مساعدة صغيرة تتكون من 2-3 أسطر - تعد إعادة استخدام التعليمات البرمجية باستخدام خطوات التعليمات البرمجية أكثر طبيعية من الوحدات النمطية

الخطوة التالية

• وحدة بناء مكتبة — 12 منصة تأتي مع وحدات مدمجة. استخدمها أولاً للتعرف على روتين استدعاء سير العمل الفرعي.
• 8 أنواع — مرجع الحقل الكامل لسير العمل الفرعي في
• أفضل الممارسات — "متى وكيف يتم التفكيك"