用途
iii-http-middleware 用于在 iii 引擎中注册引擎级中间件函数，这些函数在 HTTP 处理器之前运行。当任务需要为 HTTP 路由添加认证、请求日志、限流或任何前置处理逻辑时，可使用该技能。它类似于 Express 中间件、Fastify hooks 或 Django middleware。
主要能力
- 注册中间件函数：中间件函数像普通函数一样注册，但返回 { action: 'continue' } 或 { action: 'respond', response }，而不是普通响应。
- 挂载到 HTTP 触发器：通过触发器配置中的 middleware_function_ids 将中间件附加到 HTTP 触发器。
- 顺序执行：引擎按顺序执行中间件——第一个中间件先运行，然后是下一个，最后是处理器。
- 接收输入：中间件接收 MiddlewareFunctionInput，包含 phase、request（path_params、query_params、headers、method）以及来自认证的 context。
- 短路或放行：返回 { action: 'respond' } 会短路整条链，处理器永不运行；返回 { action: 'continue' } 则传递给下一个中间件或处理器。
架构
HTTP 请求 → iii-http（端口 3111）→ 中间件 1（continue / respond）→ 中间件 2（continue / respond）→ registerFunction 处理器 → { status_code, body, headers } 响应。
使用的 iii 原语
- registerFunction(id, handler)：定义中间件函数。
- registerTrigger({ config: { middleware_function_ids } })：将中间件附加到 HTTP 触发器。
- { action: 'continue' }：传递给下一个中间件或处理器。
- { action: 'respond', response: { status_code, body } }：短路并立即返回响应。
- req.request.headers：在中间件中访问请求头。
- req.context：访问来自 RBAC 认证函数的认证上下文。
使用方式
参考实现见 ../references/http-middleware.js，其中包含保护 HTTP 端点的认证与日志中间件的完整可运行示例。
常见模式包括：
- iii.registerFunction('middleware::auth', async (req) => { ... })——检查请求头的认证中间件。
- iii.registerFunction('middleware::rate-limit', async (req) => { ... })——限流中间件。
- iii.registerFunction('middleware::request-logger', async (req) => { ... })——请求日志。
- req.request?.headers?.authorization——读取认证令牌。
- return { action: 'respond', response: { status_code: 401, body: { error: 'Unauthorized' } } }——拒绝请求。
- return { action: 'continue' }——放行请求。
- config: { middleware_function_ids: ['middleware::auth', 'middleware::logger'] }——挂载到触发器。
适用场景与适配
- 为多个中间件串联分层关注点（日志先于认证，认证先于限流）。
- 将中间件用于多个端点共享的横切关注点。
- 结合 RBAC 认证函数实现基于角色的访问控制——认证上下文通过 req.context 流向中间件。
- 让每个中间件函数专注于单一关注点，以便复用。
限制与边界
- 如果任务只是暴露 HTTP 端点而不需要中间件，应优先使用 iii-http-endpoints。
- 如果认证需求复杂（带函数发现控制的 RBAC），应结合 RBAC worker 认证函数使用。
- 当主要需求是 HTTP 路由的前置处理时，才使用 iii-http-middleware。
- 不要将该技能作为无关任务的通用回退方案。
- 当有更具体的 iii 技能更合适时，不应使用该技能。
- 应用示例前始终验证环境与安全约束。