iii-custom-triggers

自定义触发器

类似于：自定义事件适配器、Webhook 接收器

核心概念

在适合任务的情况下使用以下概念。并非每个自定义触发器都需要用到所有概念。

• registerTriggerType(id, handler) 使用 registerTrigger 和 unregisterTrigger 回调定义一种新的触发器类型
• 处理程序接收一个 TriggerConfig，其中包含 id、function_id 和 config
• 外部事件触发时，调用 iii.trigger(function_id, event) 来调用已注册的函数
• 不再需要某种触发器类型时，使用 unregisterTriggerType 进行清理
• 不要重复使用内置触发器类型的名称：http、cron、queue、state、stream、subscribe

架构

外部事件源（Webhook、文件监视器、IoT、CDC 等）
  → 自定义触发器处理程序（registerTriggerType）
    → iii.trigger(function_id, event)
      → 已注册的函数处理事件

使用的 iii 原语

原语	用途
registerTriggerType(id, handler)	使用生命周期钩子定义一种新的触发器类型
unregisterTriggerType(id)	清理自定义触发器类型
TriggerConfig: { id, function_id, config }	传递给触发器处理程序的配置
iii.trigger(function_id, event)	事件发生时触发已注册的函数

参考实现

完整可运行的示例请参阅 ../references/custom-triggers.js — 一种用于监听外部事件并将其路由到已注册函数的自定义触发器类型。

另有 Python 版本：../references/custom-triggers.py

另有 Rust 版本：../references/custom-triggers.rs

常见模式

使用此模式的代码通常会在相关情况下包含以下内容：

• registerWorker(url, { workerName }) — 初始化 Worker
• registerTriggerType(id, { registerTrigger, unregisterTrigger }) — 定义自定义触发器
• registerTrigger(config) — 函数订阅此触发器类型时由 iii 调用
• unregisterTrigger(config) — 函数取消订阅时由 iii 调用
• iii.trigger(config.function_id, eventPayload) — 触发目标函数
• 在 unregisterTrigger 中执行清理逻辑（关闭连接、移除监听器、清除定时器）
• const logger = new Logger() — 结构化日志记录

调整此模式

在适用时使用以下调整方式。

• 选择一个能描述事件源的唯一触发器类型名称（例如 file-watcher、mqtt、db-cdc）
• 在 registerTrigger 中启动监听器（打开套接字、轮询端点、订阅主题）
• 在 unregisterTrigger 中拆除监听器，以避免资源泄漏
• 将活动监听器存储在以 config.id 为键的映射中，以便彻底注销
• 调用 iii.trigger(function_id, event) 时，在负载中传递相关事件数据

模式边界

• 如果任务使用内置 HTTP 路由，请优先选择 iii-http-endpoints。
• 如果任务使用内置 cron 计划，请优先选择 iii-cron-scheduling。
• 如果任务使用内置队列触发器，请优先选择 iii-queue-processing。
• 当 iii 没有适用于该事件源的内置触发器类型时，请使用 iii-custom-triggers。

适用场景

• 当任务主要涉及 iii 引擎中的 iii-custom-triggers 时，使用此技能。
• 当请求直接要求使用此模式或实现等效功能时，触发此技能。

边界

• 切勿将此技能作为处理无关任务的通用兜底方案。
• 如果有更具体的 iii 技能更适合，则不得使用此技能。
• 应用此技能中的示例之前，务必先核实环境和安全限制。