用途:把已注册的 iii 函数暴露为 HTTP 端点,让浏览器、Webhook、移动端或第三方服务无需 iii SDK 即可调用。它不暴露任何可调用的 http::* 函数,全部能力就是 http 触发器类型,通过 worker SDK 的触发器注册绑定,例如 iii.registerTrigger({ type: 'http', function_id, config })。
安装与冲突:使用 iii worker add http 安装。引擎内置的 iii-http 不能在同一引擎上运行,因为两者都占用 http 触发器类型;启动前需从引擎配置中移除 iii-http,否则独立 worker 拒绝启动。
主要能力:按 HTTP 方法和路径匹配请求。处理函数可收到 method、path、headers、query params、提取的 :path 参数、解析后的 body、触发器元数据以及请求/响应流通道。返回 JSON 值得到缓冲响应;向响应通道写入则得到分块流式响应。支持路径参数(如 /orders/:id)、每路由中间件、条件函数、CORS、状态码、响应头、JSON body 与分块流式响应。
绑定方式:先注册处理函数 iii.registerFunction('orders::get', handler),再注册触发器,config 中 api_path 必填,http_method 默认 GET;:name 段进入 path_params,查询串进入 query_params,请求头进入 headers。可选 condition_function_id(在中间件与处理函数前调用,返回假值则以 422 拒绝请求)和 middleware_function_ids(按列表顺序在处理函数前运行)。处理函数返回值成为带 status_code、headers、body 的缓冲响应,status_code 默认 200,body 默认空对象;流式响应需向响应通道写入 set_status、set_headers 控制消息与 body 分块,并返回 null 或不返回最终缓冲体。
配置:通过 worker http 的中央配置项设置 port(3111)、host(0.0.0.0)、default_timeout(30000)、concurrency_request_limit(1024)、cors.allowed_origins、cors.allowed_methods 与 middleware。全局中间件按优先级升序在所有路由上运行,每路由中间件在其后、处理函数前运行。middleware 与 default_timeout 支持热重载;port、host、CORS 与 concurrency_request_limit 需下次重启生效。
适用场景:Webhook、浏览器、移动应用或第三方服务需通过普通 HTTP 调用 iii 函数;需要带路径参数的路由匹配;路由需中间件或条件函数;需要在引擎边缘处理 CORS、状态码、响应头、JSON body 或分块流式响应;多个外部路由分发到普通 iii 函数而处理代码保留在自有 worker 中。
限制:不暴露可调用函数,不要调用 http::*;这是入站 HTTP,出站网络请求应使用 web::fetch;它不是调度器或事件队列,定时执行用 cron,数据变更反应用相应 state、stream、queue 或 database worker;内置 iii-http 不能与它同引擎共存;方法与路径结构等价的路由会冲突,如 /orders/:id 与 /orders/:order_id 属同一形状。