iii-trigger-conditions

触发条件

类似于：中间件守卫、事件筛选器

核心概念

任务适用时，可使用以下概念。并非每个触发器都需要条件。

• 条件函数是一个已注册的函数，返回布尔值（true 或 false）
• 引擎会在处理函数之前调用条件函数；只有返回 true 时，才会运行处理函数
• 通过触发器配置中的 condition_function_id，可为任意类型的触发器附加条件
• 条件函数接收的事件数据与处理函数接收的数据相同
• 适用于所有触发器类型：http、queue、cron、state、stream、subscribe

架构

触发器触发时，引擎首先使用事件数据调用条件函数。如果条件返回 true，处理函数就会正常执行。如果返回 false，则会静默跳过处理函数，不会报错或重试。

iii 使用的基本构件

基本构件	用途
registerFunction({ id }, handler)（条件）	注册条件函数（返回布尔值）
registerFunction({ id }, handler)（处理函数）	注册处理函数
registerTrigger({ type, function_id, config: { condition_function_id } })	将触发器绑定到条件门控

参考实现

完整可运行的示例请参阅 ../references/trigger-conditions.js ——使用条件门控的触发器

也提供 Python 版本：../references/trigger-conditions.py

也提供 Rust 版本：../references/trigger-conditions.rs 其中，业务规则函数会在处理函数处理事件之前对事件进行筛选。

常见模式

相关代码通常会在适用时包含以下内容：

• registerFunction({ id: 'conditions::is-high-value' }, async (input) => input.new_value?.amount >= 1000) — 条件函数
• registerFunction({ id: 'orders::notify-high-value' }, async (input) => { ... }) — 处理函数
• registerTrigger({ type: 'state', function_id: 'orders::notify-high-value', config: { scope: 'orders', key: 'status', condition_function_id: 'conditions::is-high-value' } }) — 绑定条件
• 条件返回 true — 执行处理函数
• 条件返回 false — 静默跳过处理函数
• 条件函数 ID 使用 conditions:: 前缀，便于整理

调整此模式

适用时，可采用以下调整方式。

• 根据业务规则替换条件逻辑（阈值检查、角色验证、功能标记）
• 条件适用于所有触发器类型：可用于 HTTP 触发器进行身份验证守卫，也可用于 queue 触发器筛选消息
• 条件函数会在每次触发器触发时运行，因此应保持轻量且快速
• 将多个业务规则合并到单个条件函数中，而不是串联多个条件
• 条件函数可以在内部调用 trigger()，以检查状态或调用其他函数

模式边界

• 通用的函数和触发器注册优先使用 iii-functions-and-triggers。
• 专门处理状态变更触发器时，优先使用 iii-state-reactions。
• 处理调用模式（sync/void/enqueue）时，优先使用 iii-trigger-actions。
• 如果主要问题是通过条件检查来控制触发器执行，则继续使用 iii-trigger-conditions。

何时使用

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

边界

• 切勿将此技能用作无关任务的通用回退方案。
• 如果有更具体的 iii 技能更适合，就不得使用此技能。
• 应用此技能中的示例前，务必先确认环境和安全约束。