inject.ctx ​

inject.ctx 定义了 inject 脚本运行时可访问的上下文字段和 helper API。

本文档只描述接口规范，不讨论设计动机和实践策略。

适用阶段 ​

• browser：脚本在浏览器环境执行。
• request：脚本在请求转发到 upstream 前执行。
• response：脚本在收到 upstream 响应后执行。

通用字段（所有阶段） ​

补充说明：

• 当 auth_required=false 且请求没有合法登录态时，ctx.safe_uid 可能为空字符串。

ctx.params 解析规则 ​

ctx.params 的源是 inject.do[].params，解析结果始终为对象。

静态值：

• 未使用 $persist 标记的值，按清单原值透传。

动态值（$persist）：

• 标记格式：{ $persist: "<key>" } 或 { $persist: "<key>", default: <any> }
• 仅当参数值显式使用 $persist 标记时触发动态解析。
• 命中持久值时返回持久值。
• 未命中且配置 default 时返回 default。
• 未命中且未配置 default 时返回 null。

阶段解析时机：

• browser：页面加载/路由变化再次触发脚本时，按当时请求上下文重新解析。
• request/response：每次命中并执行脚本前，按当次请求上下文重新解析。

额外约束：

• 解析后若结果不是对象，ctx.params 按空对象 {} 处理。

ctx.request 字段语义 ​

通用字段（所有阶段）：

阶段扩展：

ctx.runtime 字段语义（browser） ​

ctx.status 字段语义 ​

helper 概览 ​

ctx.base64 ​

用于 Base64 编码/解码。

• ctx.base64.encode(text) -> string
• ctx.base64.decode(text) -> string

ctx.persist ​

用于跨请求持久化数据，按 SAFE_UID 隔离。

request/response ​

• ctx.persist.get(key) -> any
• ctx.persist.set(key, value) -> void
• ctx.persist.del(key) -> void
• ctx.persist.list(prefix?) -> Array<{key: string, value: any}>

browser（异步） ​

• ctx.persist.get(key) -> Promise<any | undefined>
• ctx.persist.set(key, value) -> Promise<void>
• ctx.persist.del(key) -> Promise<void>
• ctx.persist.list(prefix?) -> Promise<Array<{key: string, value: any}>>

约束：

• list 返回全量结果，按 key 字典序升序。
• 不提供额外应用层加密能力（依赖系统已有加密隧道 + HTTPS）。

ctx.headers（request/response） ​

用于读取与改写 HTTP 头。

• ctx.headers.get(name) -> string
• ctx.headers.getValues(name) -> string[]
• ctx.headers.getAll() -> Record<string, string[]>
• ctx.headers.set(name, value) -> void
• ctx.headers.add(name, value) -> void
• ctx.headers.del(name) -> void

ctx.body（request/response） ​

用于读取与改写请求/响应 body。

• ctx.body.getText(opts?) -> string
• ctx.body.getJSON(opts?) -> any
• ctx.body.getForm(opts?) -> Record<string, string | string[]>
• ctx.body.set(body, opts?) -> void

opts：

补充：

• ctx.body.set(...) 会同步更新 Content-Length，并清理 Content-Encoding 与 ETag。

ctx.flow（request/response） ​

用于同一请求内的 request -> response 临时共享状态。

• ctx.flow.get(key) -> any
• ctx.flow.set(key, value) -> void
• ctx.flow.del(key) -> void
• ctx.flow.list(prefix?) -> Array<{key: string, value: any}>

ctx.fs（request/response） ​

用于读取容器文件系统状态。

• ctx.fs.exists(path) -> bool
• ctx.fs.readText(path, opts?) -> string
• ctx.fs.readJSON(path, opts?) -> any
• ctx.fs.stat(path) -> object
• ctx.fs.list(path) -> string[]

ctx.env（request/response） ​

用于读取环境变量。

• ctx.env.get(name) -> string | undefined
• ctx.env.list(prefix?) -> Record<string, string>

ctx.dump（request/response） ​

用于输出当前请求/响应内容（调试与排障）。

• ctx.dump.request(opts?) -> string
• ctx.dump.response(opts?) -> string

opts：

ctx.response（request/response） ​

用于直接构造/覆盖响应（短路返回）。

• ctx.response.send(status, body?, opts?) -> void

opts：

ctx.proxy（request/response） ​

用于按请求级别改写反代目标。

• ctx.proxy.to(url, opts?) -> void

opts：

执行模型约束 ​

• request/response 阶段为同步执行模型，不支持 Promise / async。
• browser 阶段允许异步（例如 ctx.persist Promise 调用）。