iii-trigger-conditions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Trigger Conditions

触发器条件

Comparable to: Middleware guards, event filters

可类比：中间件守卫、事件过滤器

Key Concepts

核心概念

Use the concepts below when they fit the task. Not every trigger needs a condition.

A Condition Function is a registered function that returns a boolean (
```
true
```
or
```
false
```
)
The engine calls the condition function before the handler; the handler runs only if
```
true
```
Attach a condition to any trigger type via
```
condition_function_id
```
in the trigger config
The condition function receives the same event data as the handler would
Works with all trigger types: http, queue, cron, state, stream, subscribe

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

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

Architecture

架构

When a trigger fires, the engine first invokes the condition function with the event data. If the condition returns true, the handler executes normally. If false, the handler is skipped silently with no error or retry.

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

iii Primitives Used

iii 使用的原语

Primitive	Purpose
`registerFunction({ id }, handler)` (condition)	Register the condition function (returns boolean)
`registerFunction({ id }, handler)` (handler)	Register the handler function
`registerTrigger({ type, function_id, config: { condition_function_id } })`	Bind trigger with condition gate

原语	用途
`registerFunction({ id }, handler)` (condition)	注册条件函数（返回布尔值）
`registerFunction({ id }, handler)` (handler)	注册处理器函数
`registerTrigger({ type, function_id, config: { condition_function_id } })`	将触发器与条件守卫绑定

Reference Implementation

参考实现

See ../references/trigger-conditions.js for the full working example — a condition-gated trigger

Also available in Python: ../references/trigger-conditions.py

Also available in Rust: ../references/trigger-conditions.rs where a business rule function filters events before the handler processes them.

完整的工作示例可查看../references/trigger-conditions.js —— 一个带条件守卫的触发器

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

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

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

registerFunction({ id: 'conditions::is-high-value' }, async (input) => input.new_value?.amount >= 1000)

— condition function

registerFunction({ id: 'orders::notify-high-value' }, async (input) => { ... })

— handler function

registerTrigger({ type: 'state', function_id: 'orders::notify-high-value', config: { scope: 'orders', key: 'status', condition_function_id: 'conditions::is-high-value' } })

— bind with condition

Condition returns
```
true
```
— handler executes
Condition returns
```
false
```
— handler is skipped silently
Use
```
conditions::
```
prefix for condition function IDs to keep them organized

使用此模式的代码通常包含（相关时）：

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
```
—— 处理器被静默跳过
使用
```
conditions::
```
前缀作为条件函数ID，以便进行组织

Adapting This Pattern

适配此模式

Use the adaptations below when they apply to the task.

Replace the condition logic with your business rules (threshold checks, role validation, feature flags)
Conditions work on all trigger types — use them on HTTP triggers for auth guards, on queue triggers for message filtering
Keep condition functions lightweight and fast since they run on every trigger fire
Combine multiple business rules in a single condition function rather than chaining conditions
Condition functions can call
```
trigger()
```
internally to check state or other functions

当适用时，可进行以下适配：

用你的业务规则替换条件逻辑（阈值检查、角色验证、功能标志）
条件适用于所有触发器类型 —— 在HTTP触发器上用作身份验证守卫，在队列触发器上用作消息筛选
保持条件函数轻量且快速，因为它们会在每次触发器触发时运行
在单个条件函数中组合多个业务规则，而非链式调用多个条件
条件函数可在内部调用
```
trigger()
```
来检查状态或其他函数

Pattern Boundaries

模式边界

For registering functions and triggers in general, prefer
```
iii-functions-and-triggers
```
.
For state change triggers specifically, prefer
```
iii-state-reactions
```
.
For invocation modes (sync/void/enqueue), prefer
```
iii-trigger-actions
```
.
Stay with
```
iii-trigger-conditions
```
when the primary problem is gating trigger execution with a condition check.

对于一般的函数和触发器注册，优先使用
```
iii-functions-and-triggers
```
。
对于特定的状态变更触发器，优先使用
```
iii-state-reactions
```
。
对于调用模式（同步/无返回/入队），优先使用
```
iii-trigger-actions
```
。
当主要需求是通过条件检查控制触发器执行时，使用
```
iii-trigger-conditions
```
。

When to Use

使用场景

Use this skill when the task is primarily about
```
iii-trigger-conditions
```
in the iii engine.
Triggers when the request directly asks for this pattern or an equivalent implementation.

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

Boundaries

边界限制

Never use this skill as a generic fallback for unrelated tasks.
You must not apply this skill when a more specific iii skill is a better fit.
Always verify environment and safety constraints before applying examples from this skill.

切勿将此技能用作无关任务的通用 fallback。
当更具体的iii技能更合适时，不得应用此技能。
在应用此技能中的示例前，务必验证环境和安全约束。