用途:在 iii 引擎中把已注册的函数绑定为 HTTP 路由,由 iii-http 统一在 3111 端口提供 REST 接口,适合构建 HTTP API、Webhook 和入站请求处理,且路由由 iii 自己拥有。
主要能力:每个路由是一个通过 HTTP 触发器绑定到路径与方法的注册函数;处理函数接收 ApiRequest 对象,包含 body、path_params、headers 和 method;处理函数返回 { status_code, body, headers } 来构造响应;路径参数使用冒号语法(如 /users/:id),并出现在 path_params 中;可通过触发器配置中的 middleware_function_ids 在处理器前运行中间件。
使用方式:使用 registerWorker(url, { workerName }) 初始化 worker;用 registerFunction(id, handler) 定义路由处理器;用 registerTrigger({ type: 'http', config: { api_path, http_method } }) 绑定路径与方法;POST/PUT 通过 req.body 读取解析后的请求体,路径参数通过 req.path_params 获取;返回形如 { status_code: 200, body: { data }, headers: { 'Content-Type': 'application/json' } } 的响应;可用 new Logger() 做结构化日志。参考实现见 ../references/http-endpoints.js,另有 Python 与 Rust 版本。
适用场景:需要新增路由时注册更多函数与 HTTP 触发器;用 path_params 表示资源标识(如 /orders/:orderId);返回合适状态码(201 创建、404 未找到、400 输入错误);认证路由可用中间件或检查 req.headers 中的令牌或 API Key;返回 202 Accepted 后通过队列继续处理。
限制与边界:若任务是从 iii 函数调用外部 HTTP API,应使用 iii-http-invoked-functions;若端点后需要异步处理,应使用 iii-queue-processing;若专门处理中间件链(认证、日志、限流),应使用 iii-http-middleware。仅当 iii 拥有路由并直接处理入站请求时使用本技能,不要将其作为无关任务的通用回退,应用示例前需先确认环境与安全约束。