iii-trigger-actions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Trigger Actions

Comparable to: RPC vs message queue vs fire-and-forget patterns

可类比：RPC vs 消息队列 vs 即发即弃模式

Key Concepts

核心概念

Use the concepts below when they fit the task. Not every invocation needs all three modes.

Synchronous (default): caller blocks until the function returns a result or times out
Void (
```
TriggerAction.Void()
```
): fire-and-forget dispatch, returns immediately with
```
null
```
, no retry guarantees
Enqueue (
```
TriggerAction.Enqueue({ queue })
```
): routes through a named queue with automatic retries and backoff, returns a
```
messageReceiptId
```
Decision guide: need the result? use sync. Must complete reliably? use enqueue. Optional side effect? use void.

当以下概念符合任务需求时使用。并非所有调用都需要三种模式。

Synchronous（默认）：调用方会阻塞直到函数返回结果或超时
Void (
```
TriggerAction.Void()
```
)：即发即弃式调度，立即返回
```
null
```
，无重试保障
Enqueue (
```
TriggerAction.Enqueue({ queue })
```
)：通过命名队列路由，自动重试并退避，返回
```
messageReceiptId
```
决策指南：需要结果？使用同步模式。必须可靠完成？使用入队模式。可选副作用？使用无返回值模式。

Architecture

架构

The caller invokes

trigger()

with an optional action parameter. Synchronous mode waits for the handler result. Void mode dispatches and returns null immediately. Enqueue mode places the payload on a named queue where a consumer processes it with retry guarantees.

调用方调用

trigger()

并传入可选的action参数。同步模式会等待处理程序返回结果。无返回值模式会立即调度并返回null。入队模式会将负载放入命名队列，由消费者处理并提供重试保障。

iii Primitives Used

使用的iii原语

Primitive	Purpose
`trigger({ function_id, payload })`	Synchronous invocation, blocks for result
`trigger({ ..., action: TriggerAction.Void() })`	Fire-and-forget, returns immediately with null
`trigger({ ..., action: TriggerAction.Enqueue({ queue }) })`	Durable async via named queue, returns receipt
`iii trigger --function-id=ID --payload=JSON`	CLI trigger (part of the engine binary)
`--timeout-ms`	CLI flag to set trigger timeout (default 30s)

原语	用途
`trigger({ function_id, payload })`	同步调用，阻塞等待结果
`trigger({ ..., action: TriggerAction.Void() })`	即发即弃，立即返回null
`trigger({ ..., action: TriggerAction.Enqueue({ queue }) })`	通过命名队列实现持久化异步调用，返回回执
`iii trigger --function-id=ID --payload=JSON`	CLI触发（引擎二进制文件的一部分）
`--timeout-ms`	设置触发超时时间的CLI标志（默认30秒）

Reference Implementation

参考实现

See ../references/trigger-actions.js for the full working example — a comparison of all three

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

Also available in Rust: ../references/trigger-actions.rs invocation modes showing when and how to use sync, void, and enqueue patterns.

完整的工作示例请查看../references/trigger-actions.js —— 对比了三种调用模式，展示何时以及如何使用同步、无返回值和入队模式。

同时提供Python版本：../references/trigger-actions.py

以及Rust版本：../references/trigger-actions.rs

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

await iii.trigger({ function_id: 'users::get', payload: { id } })

— sync, get result directly

iii.trigger({ function_id: 'analytics::track', payload: event, action: TriggerAction.Void() })

— fire-and-forget

iii.trigger({ function_id: 'orders::process', payload: order, action: TriggerAction.Enqueue({ queue: 'payments' }) })

— durable enqueue

Sync returns the function result directly
Void returns
```
null
```
/
```
None
```
Enqueue returns
```
{ messageReceiptId: string }
```
for tracking

iii trigger --function-id='users::get' --payload='{"id":"123"}'

— invoke via CLI

iii trigger --function-id='users::get' --payload='{"id":"123"}' --timeout-ms=5000

— with custom timeout

使用该模式的代码通常包含以下相关内容：

await iii.trigger({ function_id: 'users::get', payload: { id } })

—— 同步调用，直接获取结果

iii.trigger({ function_id: 'analytics::track', payload: event, action: TriggerAction.Void() })

—— 即发即弃

iii.trigger({ function_id: 'orders::process', payload: order, action: TriggerAction.Enqueue({ queue: 'payments' }) })

—— 持久化入队

同步模式直接返回函数结果
无返回值模式返回
```
null
```
/
```
None
```
入队模式返回
```
{ messageReceiptId: string }
```
用于追踪

iii trigger --function-id='users::get' --payload='{"id":"123"}'

—— 通过CLI调用

iii trigger --function-id='users::get' --payload='{"id":"123"}' --timeout-ms=5000

—— 自定义超时时间

Adapting This Pattern

模式适配

Use the adaptations below when they apply to the task.

Default to synchronous when the caller needs the result to proceed
Use void for logging, analytics, or any side effect where failure is acceptable
Use enqueue for anything that must complete reliably — payments, emails, notifications
Combine modes in a single handler: sync call for validation, then enqueue for processing
Named queues let you configure retries and concurrency per workload type

当以下情况适用于任务时，可使用相应的适配方式：

当调用方需要结果才能继续时，默认使用同步模式
对于日志、分析或任何可接受失败的副作用，使用无返回值模式
对于必须可靠完成的操作（如支付、邮件、通知），使用入队模式
在单个处理程序中组合多种模式：同步调用用于验证，然后入队进行处理
命名队列允许你针对不同工作负载类型配置重试和并发数

Pattern Boundaries

模式边界

For queue configuration (retries, concurrency, FIFO ordering), prefer
```
iii-engine-config
```
.
For DLQ handling when enqueued jobs exhaust retries, prefer
```
iii-dead-letter-queues
```
.
For function registration and trigger binding, prefer
```
iii-functions-and-triggers
```
.
Stay with
```
iii-trigger-actions
```
when the primary problem is choosing the right invocation mode.

对于队列配置（重试、并发、FIFO排序），优先使用
```
iii-engine-config
```
。
当入队任务耗尽重试次数时的死信队列（DLQ）处理，优先使用
```
iii-dead-letter-queues
```
。
对于函数注册和触发器绑定，优先使用
```
iii-functions-and-triggers
```
。
当主要问题是选择合适的调用模式时，使用
```
iii-trigger-actions
```
。

When to Use

使用场景

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

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

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技能更合适时，不得应用此技能。
在应用此技能中的示例之前，务必验证环境和安全约束。