跳转到内容

请求、响应与动态 Mock ​

脚本配置决定能读取哪一阶段的数据;返回给 $done 的对象决定提交哪些变更。直接修改上下文对象后,仍应通过 $done 返回需要提交的字段。

修改响应 JSON ​

下面脚本适用于 phase: response、requires_body: true 的 HTTP 规则。它只改写 JSON 对象,解析失败或返回数组、基本值时保持原文。

js
let body;
try {
  body = JSON.parse($response.body);
} catch (error) {
  console.warn("Response is not JSON:", String(error));
  $done();
}
if (body === null || typeof body !== "object" || Array.isArray(body)) {
  $done();
}
body.debug = true;
body.source = "B-box";
$done({ body: JSON.stringify(body) });

对应的完整脚本配置片段可以直接下载,源码已内嵌在 resources 中,不需要另放文件:

下载 HTTP 脚本配置

json
{
  "experimental": {
    "scripts": {
      "enabled": true,
      "http": [
        {
          "name": "Dynamic Mock",
          "pattern": "^https?://api\\.example\\.test/dynamic$",
          "phase": "request",
          "timeout_ms": 5000,
          "source": "$done({\n  response: {\n    status: 200,\n    headers: { \"Content-Type\": \"application/json\" },\n    body: JSON.stringify({ ok: true, method: $request.method, source: \"B-box script\" })\n  }\n});"
        },
        {
          "name": "Edit response JSON",
          "pattern": "^https?://api\\.example\\.test/profile(?:\\?.*)?$",
          "phase": "response",
          "requires_body": true,
          "timeout_ms": 5000,
          "resource": "response.js"
        }
      ],
      "resources": {
        "response.js": {
          "data_type": "text",
          "data": "let body;\ntry {\n  body = JSON.parse($response.body);\n} catch (error) {\n  console.warn(\"Response is not JSON:\", String(error));\n  $done();\n}\nif (body === null || typeof body !== \"object\" || Array.isArray(body)) {\n  $done();\n}\nbody.debug = true;\nbody.source = \"B-box\";\n$done({ body: JSON.stringify(body) });"
        }
      }
    }
  }
}

把 api.example.test 替换为实际域名,确认当前服务启用脚本;HTTPS 同时启用独立 MITM。命中 /profile 后,预期响应 JSON 包含 debug: true 和 source: "B-box"。

JavaScript 的 JSON.parse 使用 JS 数值,超出安全整数范围时可能丢精度。需要保留大整数的 JSON 变更,可以优先使用 jq。

修改请求 JSON ​

规则需要 phase: request 和 requires_body: true。下面代码作为 source、资源内容或脚本文件使用:

js
const body = JSON.parse($request.body);
body.debug = true;
$done({ body: JSON.stringify(body) });

这一简化例子假设请求正文是 JSON 对象。输入不满足时会产生异常,脚本不提交修改并记录告警;需要自定义兜底时像响应示例一样捕获解析错误。

动态 Mock ​

请求阶段可以通过 response 直接生成新响应:

js
$done({
  response: {
    status: 200,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ ok: true, method: $request.method, source: "B-box script" })
  }
});

生成 response.body 不要求读取请求正文,因此无需 requires_body。若返回的是顶层 body,它表示替换当前请求正文,必须开启 requires_body。

Mock 生成后仍会经过响应 Header、Body/jq 和首条匹配响应脚本。后续 Map Local 与上游请求不会继续执行。

保留重复头 ​

默认 headers 是对象,每个字段只提供第一个值。需要保留多条 Set-Cookie 等字段时,在规则上设置 full_headers: true,使用 {field,value} 数组:

js
const headers = $response.headers;
headers.push({ field: "X-Script", value: "B-box" });
$done({ headers });

这段代码对应响应脚本;不读正文时可不设 requires_body。返回头接受对象或完整头数组,但不能改动分帧/升级字段。

注意:脚本数组使用 field;声明式 Map Local 的头数组使用 name,两者写法不同。

二进制正文 ​

设置 binary_body: true 后,拦截正文以 Uint8Array 提供。需要读取或替换它仍要 requires_body: true,返回相应字节数组。

脚本主动 HTTP 请求的二进制选项名是 binary-mode,它控制网络回调的 data;不是配置字段 binary_body。两者作用范围不同。

SSE、流式 RPC、升级连接等跳过正文处理的场景不会因为启用二进制模式就变成可整体改写的正文。已知的一元 gRPC 方法可以额外设置 grpc_mode: "unary",按一元 gRPC 正文脚本处理单消息帧。

可返回字段 ​

阶段$done 接受的字段
请求url、method、headers、body、response、abort
响应status、headers、body、abort
请求 Mock 的 responsestatus、headers、body

$done({ abort: true }) 终止当前 HTTP 交换:HTTP/1 关闭连接,HTTP/2 只重置当前流,不返回合成的 502 错误页。非法 $done 结果仍可能返回 502。

Mock 状态码支持 200~999;分帧错误或不允许的字段会失败。不能人为生成 101 升级或为 HEAD/204/205/304 发送不允许的正文。

从哪里排错 ​

先核对 enabled、disabled、原始端口、应用、URL 模式和脚本顺序,再看服务日志。空正文不注入 body 属性,读取前可用 typeof $response.body 判断。记录详情按页显示正文;保存量、阅读页大小与用户设置的脚本限额是不同条件。

超时或未捕获异常会保留 前序规则已经处理后的报文,不会回滚前面完成的 Header、Body 或 jq。详细行为见处理顺序。

B-box 中文指南 · 基于实际源码整理