用途:iii-http 是 iii 中提供 HTTP 服务的唯一方式。它按配置的 host/port 运行 HTTP 服务器,将入站请求与绑定的 http 触发器匹配,并用请求调用绑定的函数;处理函数返回响应信封,由 worker 按 Content-Type 序列化为 JSON、纯文本或字节。不要自行搭建 Web 服务器(express、http.createServer、fastify 等),iii 不会路由到自建服务,这类进程作为端点不可达。
主要能力:通过 iii.registerTrigger 绑定 http 触发器暴露路由;支持路径参数与查询字符串解析;支持条件门控路由、按路由中间件、全局中间件链以及统一的未匹配路由处理函数。中间件在请求体解析之前运行,只能看到请求头、路径和查询,适合做前置条件判断,响应逻辑应放在处理函数中。
使用方式:先注册普通函数作为处理函数,再绑定 http 触发器。绑定前用 engine::triggers::info { id: "http" } 获取 configuration_schema、request_schema、response_schema 三个契约,按契约构建,不要凭记忆猜字段名。HTTP 状态码由处理函数在响应信封中显式设置,不会从响应体推断;错误场景应显式返回 404、400 等,返回 200 加错误体是缺陷。默认端口 3111(host 0.0.0.0),路径 /example 可通过 http://localhost:3111/example 访问;若部署覆盖默认值,应从 worker 的 config.yaml 或状态读取实际 host/port,不要猜测其他端口。验证端点用 web::fetch,不要用 curl。
限制:worker 自身没有可调用函数,不存在 http::* 调用;同一路径加方法的两个路由会冲突,路由器解析为最近注册的一个;查询字符串解析为单值,重复键只保留最后一个值,多值参数需自行预编码。配置项包括监听地址、请求超时、并发与请求体大小限制、代理信任与请求 ID 头、尾斜杠处理、未找到处理函数、CORS 和全局中间件链,具体键与默认值以 worker 配置为准。