iii http worker 实战：把函数直接暴露为 REST 端点（0.21.0）

iii http worker 实战：把函数直接暴露为 REST 端点（0.21.0）

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii

本文基于 iii 仓库 0.21.0 版本文档 http worker 指南，讲解如何使用内置的httpworker 将任意 worker 中的函数绑定为 HTTP 端点：从启动引擎、脚手架创建 worker、注册http触发器（含 Node / Python / Rust 三种 SDK 示例），到用 curl 验证端点，并结合引擎源码说明HttpTriggerConfig的字段定义与默认端口 3111 的来由。

http worker 解决什么问题

httpworker 把你的函数暴露为 HTTP 端点，相当于把函数变成一条 REST 路由，而无需自行搭建额外的 Web 服务器（如 Express、FastAPI 或 Axum）。你只需要：

• 在某个 worker 中注册一个处理函数；
• 注册一个type: "http"的触发器，把函数绑定到一个 HTTP 方法和路径上；
• 之后每一个匹配该方法和路径的请求，都会触发该函数执行，函数的返回值即 HTTP 响应。

安装很简单，一条命令即可把 http worker 加入项目：

iii worker add http

需要明确的一点：http worker 的服务器设置（端口、host、CORS、超时等）不在本 worker 的静态配置里写死，而是通过 configuration worker 在运行时管理，详见仓库文档 配置说明。

完整流程：从运行中的引擎到可用的端点

以下流程对应 docs/0-21-0/creating-workers/http.mdx 中的 “Create endpoints” 一节。

第 1 步：启动引擎

如果引擎尚未运行，先启动它：

iii --config config.yaml

仓库中可直接参考 engine/config.yaml——其中列出了引擎生命周期内的内置 worker（iii-stream、configuration等），并注明诸如http、state、cron、queue、pubsub、bridge这类项目级 worker 应当放在worker-compose.yaml中管理，这与iii worker add http的行为是一致的。

第 2 步：注册函数并绑定 http 触发器

如果还没有 worker，先按 worker 创建指南 用脚手架生成一个：

iii worker init my-worker --language typescript

然后编辑其源码。处理函数的入参是请求内容（body、headers、method），返回值就是响应。以下是原文档给出的三语言完整示例。

Node / TypeScript

import { registerWorker } from "iii-sdk"; const url = process.env.III_URL; if (!url) throw new Error("III_URL must be set"); const worker = registerWorker(url, { workerName: "my-worker" }); worker.registerFunction("http::add", async (payload: { body: { a: number; b: number } }) => ({ status_code: 200, body: { c: payload.body.a + payload.body.b }, headers: { "Content-Type": "application/json" }, })); worker.registerTrigger({ type: "http", function_id: "http::add", config: { api_path: "/math/add", http_method: "POST" }, });

Python

import os from iii import register_worker, InitOptions worker = register_worker( os.environ["III_URL"], InitOptions(worker_name="my-worker"), ) def add(payload: dict) -> dict: body = payload["body"] return { "status_code": 200, "body": {"c": body["a"] + body["b"]}, "headers": {"Content-Type": "application/json"}, } worker.register_function("http::add", add) worker.register_trigger({ "type": "http", "function_id": "http::add", "config": {"api_path": "/math/add", "http_method": "POST"}, })

Rust

use iii_sdk::builtin_triggers::{HttpMethod, HttpTriggerConfig}; use iii_sdk::trigger::IIITrigger; use iii_sdk::{InitOptions, RegisterFunction, register_worker}; use schemars::JsonSchema; use serde::Deserialize; use serde_json::json; #[derive(Deserialize, JsonSchema)] struct AddRequest { body: AddBody, } #[derive(Deserialize, JsonSchema)] struct AddBody { a: i64, b: i64, } let url = std::env::var("III_URL").expect("III_URL must be set"); let worker = register_worker(&url, InitOptions::default()); worker.register_function( "http::add", RegisterFunction::new(|req: AddRequest| { Ok(json!({ "status_code": 200, "body": { "c": req.body.a + req.body.b }, "headers": { "Content-Type": "application/json" } })) }), ); worker.register_trigger( IIITrigger::Http(HttpTriggerConfig::new("/math/add").method(HttpMethod::Post)) .for_function("http::add"), )?;

三个示例的共同契约：

• 函数 id 采用http::add这样的命名（带命名空间风格的前缀），触发器通过function_id与之关联；
• 返回值的status_code、body、headers三个字段分别成为 HTTP 响应的状态码、响应体与响应头；
• 触发器配置中api_path指定路由路径，http_method指定方法。

第 3 步：把 worker 加入引擎并启动

指向 worker 所在目录执行：

iii worker add ./my-worker

触发器配置的源码级细节

原文档提示路径模式、方法与响应处理有更完整的文档可查；就本仓库而言，http 触发器的配置结构定义在引擎侧的 trigger_formats.rs 中：

pub struct HttpTriggerConfig { /// HTTP endpoint path (e.g. `/users/:id`) pub api_path: String, /// HTTP method (defaults to GET) #[serde(default = "default_http_method")] pub http_method: Option<HttpMethod>, /// Optional function ID to evaluate before invoking handler pub condition_function_id: Option<String>, }

从源码结构看，可以确认三个要点：

1. api_path支持如/users/:id这样的路径模式，即路径参数是内置能力；
2. http_method可省略，默认值为 GET——因此示例中若不写http_method，端点就绑定 GET；
3. condition_function_id（0.21.0 版本文档未展开）允许在调用处理函数之前先执行一个前置函数做条件判断，这与仓库中 trigger 条件的机制相呼应，适合做路由级的前置校验。

调用端点

触发器注册后，直接在引擎的 HTTP 端口上调用该路径即可。http worker 默认监听3111端口——这一默认值在仓库的 worker-compose.yaml 中（port: 3111）以及 configuration worker 的配置模板（${HTTP_PORT:3111}，见 configuration.rs）中都能找到对应依据：

# 调用已暴露的函数 curl -X POST http://localhost:3111/math/add -H 'content-type: application/json' -d '{"a":2,"b":3}'

按示例逻辑，该请求应返回状态码 200、响应体{"c":5}。

运行时服务器配置

文档特别指出，http worker 的端口、host、CORS、超时等服务器设置通过 configuration worker 在运行时管理，而不是写死在 worker 定义里。这意味着：

• 修改监听端口、开启 CORS 或调整超时，走 configuration worker 的运行时通道即可，无需重新部署 worker 本身；
• 引擎侧对这类配置值还做了模板插值与类型强制（例如${HTTP_PORT:3111}会被校验为整数 3111 而非字符串），相关测试见 store.rs 中围绕端口模板的断言。

小结

• 用iii worker add http引入 http worker，函数即路由，无需自建 Web 服务器；
• 端点 = 函数 + 一个{ type: "http", function_id, config: { api_path, http_method } }触发器，http_method省略时为 GET；
• 端点默认暴露在引擎 HTTP 端口3111上，可用 curl 直接验证；
• 路径参数模式、方法、响应处理见api_path/HttpTriggerConfig定义（engine/src/trigger_formats.rs），端口/CORS/超时等服务器设置由 configuration worker 运行时管理。

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii