Dùng lại và thu nhỏ

Khi bạn tiếp cận quy trình làm việc thứ hai và thứ ba, bạn sẽ thấy rằng một phần logic nhất định xuất hiện liên tục - lấy dữ liệu ASA, gửi tin nhắn Telegram và tạo báo cáo Excel. Nếu tiếp tục sao chép và dán, bạn sẽ phải thay đổi ba nơi để thay đổi một nơi, thử nghiệm sẽ được lặp lại và phiên bản sẽ mất kiểm soát. Đã đến lúc thực hiện mô-đun hóa vào lúc này.

"Mô-đun" là gì?

Một "module" bản chất là một workflow khai báo trường cấp cao WorkflowModuleContract. Nó công khai thêm:

• inputs — Các tham số mà người gọi phải chuyển vào (có tên, loại, bắt buộc, giá trị mặc định, mô tả)
• outputs — Kết quả có cấu trúc được tạo sau khi thực thi (có thể được người gọi trực tiếp tham chiếu)
• version — Số phiên bản ngữ nghĩa để hỗ trợ khóa người gọi

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 …

Sau khi có hợp đồng, bước sub_workflow của người gọi (quy trình làm việc gốc) sẽ:

• Xác minh tĩnh khi lưu - đầu vào bắt buộc sẽ không được lưu nếu thiếu một đầu vào;
• Xác minh trong thời gian chạy - nếu loại không khớp/điều tra không có trong danh sách, lỗi sẽ được báo cáo trực tiếp;
• Tự động hoàn thành trong trình chỉnh sửa - khi bạn viết đầu vào: bạn có thể cuộn xuống để xem mô-đun hiển thị trường nào.

Cách quy trình làm việc gốc gọi mô-đun

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 存到你自己的数据库，方便后续更新那条消息 ...

Những điểm chính:

• module: dingyue-module-slack-deliver Đó là id mô-đun và nền tảng sẽ giải quyết nó dựa trên tên + phiên bản.
• inputs: Tương ứng 1-1 với các đầu vào trong hợp đồng mô-đun.
• Sau khi cuộc gọi hoàn tất, bạn có thể chuyển {{steps.deliver.outputs.message_id}} Đọc đầu ra mô-đun.

Biến workflow hiện có thành mô-đun: Thăng cấp lên mô-đun

Trong hầu hết các trường hợp, bạn sẽ không viết mô-đun từ đầu mà lấy mô-đun đó từ quy trình làm việc hiện có. Quá trình:

1. Mở một workflow mà bạn thấy "đoạn logic này đáng tái sử dụng".
2. Sử dụng lựa chọn khung chuột hoặc Shift+click để chọn một số bước liên tiếp trong khung vẽ.
3. Menu chuột phải → "Thăng cấp lên mô-đun" hoặc nút có cùng tên trên thanh công cụ trên cùng.
4. Trong cửa sổ bật lên:
   • Đặt tên mô-đun có ý nghĩa (duy nhất trên toàn cầu, bạn nên thêm tiền tố vào tên nhóm của mình, ví dụ: my-team-slack-notifier);
   • Nền tảng sẽ tự động suy ra bản nháp đầu vào / đầu ra đầu tiên dựa trên đoạn đã chọn mà bạn có thể chỉnh sửa;
   • Sau khi xác nhận, nhấp vào "Tạo mô-đun".
5. Các bước này trong quy trình làm việc ban đầu sẽ được thay thế bằng nút sub_workflow - các tham số và kết nối được căn chỉnh tự động.

Nâng cấp mô-đun và khả năng tương thích phiên bản

Mỗi lần bạn lưu một mô-đun, một phiên bản mới sẽ được tạo. Có thể chọn workflow gốc ở bước sub_workflow:

• version: latest — Tự động sử dụng phiên bản mới nhất (phù hợp với module bạn tự bảo trì)
• version: "1.2.0" — Bị khóa một phiên bản cụ thể (thích hợp để tham khảo module của người khác, sợ nâng cấp làm hỏng tính tương thích)
• version: "^1.2.0" — Cho phép nâng cấp phiên bản nhỏ, cấm các phiên bản chính có nhiều phiên bản

Thế nào là "thay đổi tương thích"?

• ✓ Thêm đầu vào tùy chọn (giá trị bắt buộc/mặc định không được coi là bị hỏng)
• ✓ Thêm trường đầu ra
• ✗ Xóa/đổi tên đầu vào
• ✗ Xóa/đổi tên đầu ra
• ✗ Thay đổi kiểu đầu vào

Khi thực hiện các thay đổi làm hỏng tính tương thích, phiên bản ngữ nghĩa phải được nâng cấp lên CHÍNH tiếp theo. Nền tảng không thực thi nhưng được bảo vệ khi người gọi khóa ^X.Y.Z.

Phát hiện vòng lặp

Mô-đun A không thể tham chiếu gián tiếp đến chính nó. Nền tảng thực hiện phát hiện ở hai cấp độ:

1. Phát hiện tĩnh tại thời điểm phát hành — Khi lưu mô-đun, DFS quét biểu đồ phụ thuộc của tất cả các mô-đun khác mà nó tham chiếu và từ chối lưu nếu có vòng lặp.
2. Phát hiện động thời gian chạy — Nếu một chu trình được giải quyết bằng thời gian chạy xảy ra trong quá trình thực thi (ví dụ: nó được tham chiếu sau một nhánh có điều kiện), thì lỗi sẽ được đưa ra ngay lập tức.

Độ sâu đệ quy tối đa mặc định 8 tầng. Đây là độ sâu "cha gọi con gọi cháu", không phải fanout của một lần gọi.

Cách ly biến

Module khi chạy là một "WorkflowExecutionContext con", cách ly hoàn toàn với ngữ cảnh cha:

• Theo mặc định, các biến/đầu ra bước/Agent của cha mẹ không được kế thừa cho con;
• Đầu ra bước nội bộ của con sẽ không tràn sang cha mẹ - cha mẹ chỉ có thể xem kết quả đầu ra được khai báo trong hợp đồng;
• Cách duy nhất để truyền dữ liệu giữa cha và con là đầu vào/đầu ra (hợp đồng rõ ràng).

Sự cách ly này là nền móng cho độ tin cậy của mô-đun hóa — "hộp đen" không phải ẩn dụ mà là nghĩa đen.

Giảm hạng khỏi mô-đun: Khôi phục mô-đun về bước nội tuyến

Nếu bạn sửa đổi nó và nhận thấy rằng một đoạn logic nhất định thực sự chỉ được sử dụng ở một nơi và việc biến nó thành một mô-đun sẽ làm tăng chi phí hiểu biết, bạn có thể đảo ngược Hạ cấp:

1. Chọn nút sub_workflow trong quy trình làm việc chính;
2. Nhấp chuột phải → "Hạ cấp nội tuyến";
3. Nền tảng mở rộng bước của mô-đun trở lại quy trình làm việc gốc và nút sub_workflow biến mất.

Bản thân mô-đun gốc không bị xóa - nếu có các workflow khác tham chiếu đến mô-đun đó thì các quy trình đó vẫn hợp lệ.

Nơi quản lý tất cả các mô-đun

Điều hướng chính "Thư viện mô-đun" ở bên trái là chế độ xem tổng quan của bạn. Tại đây bạn có thể:

• Xem danh sách tất cả các mô-đun (bao gồm 12 mô-đun + những mô-đun do nhóm của bạn tạo)
• Truy vấn ngược theo "ai đang tham chiếu tôi" — trước khi sửa module hãy xem ai bị ảnh hưởng
• Xem lịch sử phiên bản mô-đun/khác biệt
• Xuất bản/Lưu trữ/Chuyển quyền sở hữu

Khi nào cần tạo mô-đun

• ✓ Đoạn logic giống nhau xuất hiện trong hơn 2 workflow
• ✓ Một đoạn logic ổn định và có hợp đồng rõ ràng với bên ngoài (điển hình như "gửi tin / tra báo cáo / tạo Markdown")
• ✓ Một quy trình làm việc đơn lẻ đã vượt quá 15 bước và khả năng đọc của nó đã giảm đi.
• ✗ Một đoạn logic chỉ được sử dụng một lần và sẽ không được sử dụng lại trong tương lai - được nội tuyến trực tiếp
• ✗ Chức năng tiện ích nhỏ gồm 2–3 dòng - tái sử dụng mã bằng các bước mã tự nhiên hơn mô-đun

Bước tiếp theo

• Thư viện mô- đun có sẵn — 12 nền tảng đi kèm với các mô-đun tích hợp. Trước tiên, hãy sử dụng chúng để làm quen với quy trình gọi sub_workflow.
• 8 Bước — Tham chiếu trường đầy đủ cho sub_workflow trong
• Thực hành tốt nhất — "Khi nào tách, tách thế nào"