iii-functions-and-triggers

函数与触发器

可与以下内容相比较：无服务器函数运行时、Lambda、Cloud Functions

核心概念

在适合任务的情况下使用以下概念。并非每个 worker 都需要全部概念。

• Function 是使用唯一 ID 注册的异步处理程序
• Trigger 将事件源绑定到函数，类型包括 http、queue、cron、state、stream 和 subscribe
• 函数通过 trigger() 调用其他函数，无论语言或 worker 所在位置如何
• 引擎会自动处理序列化、路由和传递
• 由 HTTP 调用的函数会将外部端点包装为可调用的函数 ID
• 函数可以声明请求／响应格式，以用于文档编写和发现——Rust（通过 schemars::JsonSchema）和 Python（通过类型提示／Pydantic）可根据类型自动生成，Node.js 则需手动提供

架构

registerWorker() 将 worker 连接到引擎，registerFunction 定义处理程序，registerTrigger 将事件源绑定到这些处理程序，而引擎会将传入事件路由到正确的函数。函数可以通过 trigger() 跨 worker 和语言调用其他函数。

使用的 iii 原语

原语	用途
registerWorker(url, options?)	将 worker 连接到引擎
registerFunction({ id }, handler)	定义函数处理程序
registerTrigger({ type, function_id, config })	将事件源绑定到函数
trigger({ function_id, payload })	同步调用函数
trigger({ ..., action: TriggerAction.Void() })	发起即弃式调用
trigger({ ..., action: TriggerAction.Enqueue({ queue }) })	通过队列进行持久化异步调用

参考实现

• TypeScript：../references/functions-and-triggers.js
• Python：../references/functions-and-triggers.py
• Rust：../references/functions-and-triggers.rs

每个参考实现都展示了相同模式（函数注册、触发器绑定、跨函数调用）在相应语言中的用法。

常见模式

使用此模式的代码通常会在适用时包含以下内容：

• registerWorker('ws://localhost:49134', { workerName: 'my-worker' }) — 连接到引擎
• registerFunction({ id: 'namespace::name' }, async (input) => { ... }) — 注册处理程序
• registerTrigger({ type: 'http', function_id, config: { api_path, http_method } }) — HTTP 触发器
• registerTrigger({ type: 'queue', function_id, config: { topic } }) — 队列触发器
• registerTrigger({ type: 'cron', function_id, config: { expression } }) — cron 触发器
• registerTrigger({ type: 'state', function_id, config: { scope, key } }) — 状态变更触发器
• registerTrigger({ type: 'stream', function_id, config: { stream } }) — 流触发器
• registerTrigger({ type: 'subscribe', function_id, config: { topic } }) — 发布／订阅订阅者
• 跨语言调用：TypeScript 函数可以通过 ID 触发 Python 或 Rust 函数

请求／响应格式（自动注册）

函数可以声明其输入／输出架构，以用于文档编写和发现：

• Rust：在处理程序的输入／输出类型上派生 schemars::JsonSchema——RegisterFunction::new() 会根据类型自动生成 JSON Schema（Draft 7）
• Python：在处理程序参数和返回类型上使用类型提示（Pydantic 模型或基本类型）——register_function() 会自动提取 JSON Schema（Draft 2020-12）
• Node.js：在注册消息中手动传入 request_format／response_format（例如，通过 Zod 的 toJSONSchema()）

调整此模式

在适用于当前任务的情况下，使用以下调整方式。

• 将占位处理逻辑替换为实际业务逻辑（API 调用、数据库查询、大模型调用）
• 使用 namespace::name 约定为函数 ID 命名，以便对相关函数进行分组
• 对于 HTTP 端点，在触发器配置中设置 api_path 和 http_method
• 对于持久化异步工作，使用 TriggerAction.Enqueue({ queue })，而非同步触发器
• 对于即发即弃的副作用，使用 TriggerAction.Void()
• 使用不同语言的多个工作进程可以注册能够通过 ID 相互调用的函数

模式边界

• 对于 HTTP 端点的具体细节（请求／响应格式、路径参数），优先使用 iii-http-endpoints。
• 对于队列处理的详细信息（重试、并发、先进先出），优先使用 iii-queue-processing。
• 对于 cron 调度的详细信息（表达式、时区），优先使用 iii-cron-scheduling。
• 对于调用模式（同步、void、入队），优先使用 iii-trigger-actions。
• 当主要问题是注册函数、绑定触发器或跨语言调用时，使用 iii-functions-and-triggers。

适用场景

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

边界

• 切勿将此技能作为处理无关任务的通用兜底方案。
• 如果有更具体的 iii 技能更适合，切勿应用此技能。
• 应用此技能中的示例前，务必确认环境和安全约束。