iii http worker 实战：把函数变成 HTTP 端点，从零到可调用的 REST 路由

iii http worker 实战：把函数变成 HTTP 端点，从零到可调用的 REST 路由

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

本文基于 iii 仓库中 HTTP worker 使用文档 展开，介绍如何在 iii 引擎中用httpworker 将函数暴露为 HTTP 端点：从引擎启动、worker 脚手架、触发器绑定，到端点调用的完整链路，并结合 引擎源码 深入解析 http 触发器的配置字段、请求载荷与响应契约，以及 worker-compose.yaml 中的服务器级配置（端口、CORS、超时等）。读完后你可以直接在 iii 中注册一个可被 curl 调用的 REST 路由，并理解其背后的请求分发机制。

http worker 是什么

httpworker 将你的函数暴露为 HTTP 端点，让你无需搭建独立的 Web 服务器就能把函数变成 REST 路由。引擎启动后，该 worker 会在独立的 HTTP 端口上监听请求（默认3111），当请求匹配某个已注册http触发器的method + path时，引擎就会调用对应函数，并把函数的返回值组装成 HTTP 响应。

一键安装该 worker：

iii worker add http

需要注意的是：路径模式、方法、请求头与响应处理的细节由 worker 自身能力决定，而服务器级设置（端口、host、CORS、超时）则在运行时通过 configuration worker 管理（参见 配置文档）。

触发器配置：httptrigger 的完整字段

引擎在 trigger_formats.rs 中定义了 http 触发器的配置结构，这是所有 SDK 中register_trigger({ type: "http", ... })的底层契约：

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>, } pub enum HttpMethod { GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, }

三个字段的关键含义：

此外，trigger.rs 中的trigger_request_format_for/call_request_format_for/call_response_format_for为http类型注册了三份自动生成的 JSON Schema：注册时所需的配置格式、handler 收到的请求格式、以及 handler 必须返回的响应格式（通过engine::triggers::info暴露，方便调用方发现契约）。

函数接收什么、返回什么

请求载荷：HttpCallRequest

每当匹配请求到达，绑定的 handler 会收到 HttpCallRequest 描述的载荷：

pub struct HttpCallRequest { pub query_params: HashMap<String, String>, // URL 查询参数 pub path_params: HashMap<String, String>, // 路径参数（如 /users/:id 中的 id） pub headers: HashMap<String, String>, // 请求头 pub path: String, // 请求路径 pub method: String, // HTTP 方法 pub body: Value, // 请求体 }

也就是说，原文档中“handler 接收请求（body、headers、method）”这一点在源码中被精确化为：handler 实际拿到的是包含查询参数、路径参数、请求头、路径、方法与请求体的完整结构。

响应契约：HttpCallResponse

handler 的返回值会被解析为 HttpCallResponse 响应信封，所有字段均为可选，缺省时取默认值：

pub struct HttpCallResponse { /// HTTP status code，省略时默认 200（字段名是 status_code，不是 status） pub status_code: Option<u16>, /// 响应头，支持 {"Header-Name": "value"} map 或 ["Header-Name: value"] 数组两种形式 pub headers: Option<HttpResponseHeaders>, /// 响应体，按你设置的 Content-Type 序列化为 JSON、文本或字节；省略时默认空对象 pub body: Option<Value>, }

要点：

• 错误场景请显式返回status_code（如 404、400），省略则默认 200；
• headers既可以是对象 map，也可以是"Header-Name: value"字符串数组，worker 两种形式都读；
• body的最终线上格式由你设置的Content-Type决定（JSON / 文本 / 字节流）。

从引擎到端点的完整实操

下面是文档给出的完整链路：从运行中的引擎到一个可调用的端点。

第一步：启动引擎

如果引擎尚未运行：

iii --config config.yaml

第二步：创建 worker 并注册函数 + http 触发器

如果还没有 worker，用脚手架生成一个（详见 worker 文档）：

iii worker init my-worker --language typescript

然后在 worker 源码中注册要暴露的函数，并绑定一个http触发器。下面三种语言的完整示例均暴露POST /math/add端点。

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"), )?;

注意 Rust 示例中的AddRequest结构体只声明了body字段：handler 的反序列化结构只需声明你关心的字段即可，query_params、path_params、headers等其余字段按需声明（对应HttpCallRequest中的各成员）。

第三步：启动 worker

iii worker add ./my-worker

服务器级配置：端口、host、CORS 与并发

http worker 的服务器参数不在 worker 代码里写，而是由引擎侧的 worker 注册配置下发。worker-compose.yaml 中可以看到该 worker 的完整运行配置：

http: worker: package://api.workers.iii.dev/http version: "0.21.3" config_name: http config_override: port: 3111 host: 127.0.0.1 default_timeout: 30000 concurrency_request_limit: 1024 cors: allowed_origins: - http://localhost:3000 - http://localhost:5173 allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]

各参数含义：

• port: 3111：引擎对外 HTTP 端口，也是下文 curl 调用使用的端口；
• host: 127.0.0.1：默认只监听本机回环地址；
• default_timeout: 30000：请求处理超时（毫秒）；
• concurrency_request_limit: 1024：并发请求上限；
• cors：允许跨域的来源与方法白名单。

这些设置即文档中提到的“通过 configuration worker 在运行时管理”的http配置项（config_name: http），修改后 worker 会响应配置变更事件重新加载服务器参数。

调用端点

触发器注册完成后，直接在引擎的 HTTP 端口（默认3111）上调用路径即可：

# call the exposed function curl -X POST http://localhost:3111/math/add -H 'content-type: application/json' -d '{"a":2,"b":3}'

请求经 http worker 匹配POST /math/add触发器 → 组装HttpCallRequest载荷投递给 worker 中的http::add函数 → 函数返回的{status_code, body, headers}被按HttpCallResponse契约序列化为 HTTP 响应。预期响应体为{"c":5}。

小结与延伸阅读

本文覆盖的要点：

1. iii worker add http安装 worker，iii worker init+iii worker add完成端点上线；
2. http 触发器配置三要素：api_path（必填，支持:param路径占位符）、http_method（默认 GET）、condition_function_id（可选前置函数）；
3. handler 契约：入参为含query_params/path_params/headers/path/method/body的完整请求结构，返回值为可选字段的status_code/headers/body响应信封；
4. 服务器参数（端口 3111、host、超时、并发上限、CORS）通过 worker-compose.yaml 与 configuration worker 在运行时管理。

进一步阅读：trigger 触发器文档、worker 脚手架文档、配置管理文档，以及源码中的 trigger_formats.rs（各内置触发器类型的完整载荷定义）与 trigger.rs（触发器注册与 Schema 暴露机制）。

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