iii-trigger-actions

触发操作

可与以下模式相比较：RPC、消息队列与即发即弃模式

核心概念

在适用于任务时使用以下概念。并非每次调用都需要包含这三种模式。

• 同步（默认）：调用方会阻塞，直到函数返回结果或超时
• Void（TriggerAction.Void()）：即发即弃式分发，立即返回 null，不保证重试
• Enqueue（TriggerAction.Enqueue({ queue })）：通过指定名称的队列路由，并自动重试和退避，返回 messageReceiptId
• 选择指南：需要结果？用同步。必须可靠完成？用 enqueue。可有可无的副作用？用 void。

架构

调用方使用可选的 action 参数调用 trigger()。同步模式会等待处理程序返回结果。Void 模式会分发并立即返回 null。Enqueue 模式会将载荷放入指定名称的队列，由消费者处理，并提供重试保障。

iii 基本操作

基本操作	用途
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 标志（默认值为 30s）

参考实现

完整可运行示例见 ../references/trigger-actions.js，其中对比了全部三种调用模式，展示何时以及如何使用同步、void 和 enqueue 模式。

另有 Python 版本：../references/trigger-actions.py

另有 Rust 版本：../references/trigger-actions.rs

常见模式

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

• 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' }) }) — 持久化入队
• 同步调用直接返回函数结果
• Void 返回 null / None
• Enqueue 返回 { messageReceiptId: string }，以便跟踪
• iii trigger --function-id='users::get' --payload='{"id":"123"}' — 通过 CLI 调用
• iii trigger --function-id='users::get' --payload='{"id":"123"}' --timeout-ms=5000 — 使用自定义超时

调整此模式

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

• 当调用方需要结果才能继续时，默认使用同步模式
• 对于日志记录、分析或任何可接受失败的副作用，使用 void
• 对于必须可靠完成的任务（如付款、电子邮件和通知），使用 enqueue
• 在单个处理程序中组合模式：同步调用进行验证，然后使用 enqueue 处理
• 指定名称的队列可让你按工作负载类型配置重试和并发

模式适用范围

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

适用场景

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

适用范围

• 切勿将此技能用作无关任务的通用备选方案。
• 如果有更具体的 iii 技能更适合，则不得使用此技能。
• 应用此技能中的示例前，务必验证环境和安全限制。