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 响应。一键安装该 workeriii 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: OptionHttpMethod, /// Optional function ID to evaluate before invoking handler pub condition_function_id: OptionString, } pub enum HttpMethod { GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, }三个字段的关键含义字段必填说明api_path是端点路径支持/users/:id这样的路径参数占位符。缺失时引擎注册会直接失败engine/mod.rs 中的测试验证了报错信息为api_path is requiredhttp_method否支持的 HTTP 方法枚举值包括GET / POST / PUT / DELETE / PATCH / HEAD / OPTIONS省略时默认为 GET见 default_http_methodcondition_function_id否可选的“前置条件函数”在调用实际 handler 之前先执行返回真才继续调用用于实现访问控制或路由级过滤此外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: HashMapString, String, // URL 查询参数 pub path_params: HashMapString, String, // 路径参数如 /users/:id 中的 id pub headers: HashMapString, String, // 请求头 pub path: String, // 请求路径 pub method: String, // HTTP 方法 pub body: Value, // 请求体 }也就是说原文档中“handler 接收请求body、headers、method”这一点在源码中被精确化为handler 实际拿到的是包含查询参数、路径参数、请求头、路径、方法与请求体的完整结构。响应契约HttpCallResponsehandler 的返回值会被解析为 HttpCallResponse 响应信封所有字段均为可选缺省时取默认值pub struct HttpCallResponse { /// HTTP status code省略时默认 200字段名是 status_code不是 status pub status_code: Optionu16, /// 响应头支持 {Header-Name: value} map 或 [Header-Name: value] 数组两种形式 pub headers: OptionHttpResponseHeaders, /// 响应体按你设置的 Content-Type 序列化为 JSON、文本或字节省略时默认空对象 pub body: OptionValue, }要点错误场景请显式返回status_code如 404、400省略则默认 200headers既可以是对象 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 / TypeScriptimport { 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 }, });Pythonimport os from iii import register_worker, InitOptions worker register_worker( os.environ[III_URL], InitOptions(worker_namemy-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}, })Rustuse 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中的各成员。第三步启动 workeriii 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}。小结与延伸阅读本文覆盖的要点iii worker add http安装 workeriii worker initiii worker add完成端点上线http 触发器配置三要素api_path必填支持:param路径占位符、http_method默认 GET、condition_function_id可选前置函数handler 契约入参为含query_params/path_params/headers/path/method/body的完整请求结构返回值为可选字段的status_code/headers/body响应信封服务器参数端口 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考