企业官网建设流程全解析

如何用 iii http worker 快速把函数变成 REST 端点（完整指南）

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

手上有个函数，哪怕只是算两个数的和，你希望别的系统能通过 HTTP 调用它，但不想再搭一套 Express 或 FastAPI——这正是 iii http worker 解决的场景：在 worker（你自建的、承载业务函数的独立服务进程）里注册一个函数，再绑定一个 http 触发器（trigger，即「匹配到什么事件就执行哪个函数」的绑定声明），函数就成了一个监听在默认端口 3111 上的 REST 端点。本文带你走一遍 iii 创建 REST 端点的完整过程，从引擎（engine，iii 的常驻主进程，负责注册与路由各请求）启动到用 curl 验证响应，总共只有几条命令。

engine、worker 与 trigger 的关系

把引擎想成话务台，worker 是话务台里的一间办公室，trigger 则是通讯录上的分机分配条：请求进来，话务台按分机把呼叫转给对应办公室。http worker 负责的是对外 HTTP 这条线路——它监听端口，把每个匹配「方法 + 路径」的请求转发给你注册的函数，函数的返回值原样变成 HTTP 响应。

和自建 Web 服务器相比，分工是这样的：

configuration worker 是引擎内置的一个特殊 worker，专门管理其他 worker 的运行时配置，所以调整监听端口这类操作不需要重新部署 http worker 本身。

4 条命令搭出第一个端点

先把 http worker 加入项目。项目级 worker 由所在目录的 worker-compose.yaml 统一管理，这条命令就是把它登记进去：

iii worker add http

预期看到 worker-compose.yaml 中出现 http 条目，带有默认端口、host 与 CORS 规则。

如果引擎还没运行，先启动它：

iii --config config.yaml

预期看到引擎进入常驻状态，配置文件里声明的内置 worker（configuration、state 等）陆续上线。

接着用脚手架生成一个新 worker（从零写 worker 可参考worker 创建指南）：

iii worker init my-worker --language typescript

预期在当前目录生成 my-worker，里面已包含 SDK 连接代码。现在把处理函数注册进去——入参是请求内容，返回值的status_code、body、headers三个字段分别对应响应的状态码、响应体和响应头：

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

Python 与 Rust 的 SDK 结构完全一致：注册同名函数，再用相同形状的 config 调register_trigger，完整样例见仓库 docs 目录下的 http worker 指南。最后把函数绑定到POST /math/add：

worker.registerTrigger({ type: "http", function_id: "http::add", config: { api_path: "/math/add", http_method: "POST" }, });

把 worker 挂入引擎，指向它的目录即可：

iii worker add ./my-worker

预期看到引擎的 worker 列表里出现 my-worker。从这一刻起，发往 /math/add 的 POST 请求都会执行你的函数。

iii http 触发器配置的 3 个字段

触发器配置总共就 3 个字段，结构体定义在引擎侧的 trigger_formats.rs，默认行为也都能从注释里确认：

两个细节值得留意。其一，api_path不是普通字符串，写成:id的段就是路径参数，函数内部可直接取到具体值，不需要自己解析 URL。其二，http_method省略时按 GET 处理——写只读端点时这个字段可以直接省掉。至于condition_function_id，它相当于路由层的「门卫」：请求先经过一个前置函数，判断通过才进入真正的业务函数，适合放鉴权或参数校验这类逻辑。

用 curl 验证，再避开 3 个坑 📌

触发器注册后直接请求引擎的 HTTP 端口。http worker 默认监听 3111，仓库里的 worker-compose.yaml 中直接写着port: 3111：

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

预期得到 200，响应体是{"c":5}。如果结果不符，按顺序排查这几种情况：

1. 连接被拒绝——引擎没启动。先执行iii --config config.yaml，再发请求。
2. 引擎在跑但返回 404——方法或路径不匹配。最典型的是代码里忘了写http_method，触发器实际绑的是 GET，而 curl 发的是 POST；把触发器注册和-X的值逐字对照一遍。
3. 3111 端口被占用——端口不必固定。端口、host、CORS、超时这些服务器设置都由 configuration worker 在运行时管理，按配置文档走它的通道改端口即可，改完即时生效，无需重新部署 worker。

除了 curl，也可以从控制台验证：Triggers 页面左侧列出全部触发器，右侧面板选中一个 http 触发器后，填好参数点 SEND REQUEST 就能直接发请求，见下图。

接下来可以看什么

一个函数加一条触发器，就是一个 REST 端点；在 iii 里扩一个新接口的成本，只是多注册一个函数和几行配置，而监听、CORS、超时这些服务器层面的琐事都交给了引擎。等熟悉这套写法后，还可以把 http 和 queue、cron 触发器组合起来：同步入口走 http，异步任务丢进队列，定时调度交给 cron。

延伸阅读：

• http worker 指南：路径模式、方法、请求与响应处理的完整说明
• configuration worker 文档：运行时修改端口、CORS 与超时的具体操作

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