iii-http-endpoints

HTTP 端点

类似于：Express、Fastify、Flask

核心概念

在适合任务的情况下使用以下概念。并非每个 HTTP 端点都需要用到所有概念。

• 每条路由都是一个通过 HTTP 触发器绑定到路径和方法的已注册函数
• 处理程序会接收一个 ApiRequest 对象，其中包含 body、path_params、headers 和 method
• 处理程序返回 { status_code, body, headers } 来构造 HTTP 响应
• RestApiModule 会在端口 3111 上提供所有已注册路由
• 路径参数使用冒号语法（例如 /users/:id），并会出现在 path_params 中

架构

HTTP 请求
  → RestApiModule（端口 3111）
    → registerTrigger 匹配路由（方法 + 路径）
      → registerFunction 处理程序（接收 ApiRequest）
        → { status_code, body, headers } 响应

使用的 iii 基元

基元	用途
registerFunction	定义路由的处理程序
registerTrigger({ type: 'http' })	将路由路径和方法绑定到函数
config: { api_path: '/path', http_method: 'GET' }	在触发器上配置路由

参考实现

完整的可运行示例请参阅 ../references/http-endpoints.js —— 一个通过参数化路由处理 GET 和 POST 请求的 REST API。

另有 Python 版本：../references/http-endpoints.py

另有 Rust 版本：../references/http-endpoints.rs

常见模式

使用此模式的代码通常会在适用时包含以下内容：

• registerWorker(url, { workerName }) — 初始化 worker
• registerFunction(id, handler) — 定义路由处理程序
• registerTrigger({ type: 'http', config: { api_path, http_method } }) — 绑定路径和方法
• req.body — 解析后的 POST/PUT 请求体
• req.path_params — 提取的路径参数
• return { status_code: 200, body: { data }, headers: { 'Content-Type': 'application/json' } } — 响应结构
• const logger = new Logger() — 在每个处理程序中进行结构化日志记录

调整此模式

在适用时使用以下调整方式。

• 通过注册其他具有不同路径或方法的函数和 HTTP 触发器来添加更多路由
• 使用 path_params 获取资源标识符（例如 /orders/:orderId）
• 返回适当的状态码（创建时为 201，未找到时为 404，输入无效时为 400）
• 对于经过身份验证的路由，检查 req.headers 中的令牌或 API 密钥
• 在端点返回 202 Accepted 后，将任务加入队列，以便在后台继续处理

模式边界

• 如果任务是从 iii 函数调用外部 HTTP API，请优先选择 iii-http-invoked-functions。
• 如果需要在端点后进行异步处理，请优先选择 iii-queue-processing 来执行后台工作。
• 当 iii 拥有路由并直接处理传入请求时，使用 iii-http-endpoints。

何时使用

• 当任务主要涉及 iii 引擎中的 iii-http-endpoints 时，使用此技能。
• 当请求直接要求使用此模式或实现等效功能时，触发此技能。

边界

• 切勿将此技能用作无关任务的通用兜底方案。
• 如果有更具体的 iii 技能更适合，切勿应用此技能。
• 应用此技能中的示例前，务必确认环境和安全约束。