自定义函数使用文档

面向使用者的操作指南。菜单位置：接口测试 → 自定义函数。 自定义函数是用 JavaScript 编写的可复用函数，用于内置函数覆盖不到的场景：请求签名、加密、拼装动态值等。定义一次，在接口参数、脚本、UI 场景中随处调用。

一、页面布局

• 左侧：函数列表，支持搜索、新建；每个函数的「更多」菜单提供复制调用表达式和删除
• 右侧：编辑区 + 试运行面板

二、新建与编辑

1. 点「新建函数」，填写：
   • 函数名称：如「请求签名」（调用时按名字识别，见下文）
   • 参数定义：逗号分隔，如 text,key；无参可留空
   • 描述：用途说明（可选）
   • 函数体：JavaScript 代码，用 return 返回结果
2. 点「保存」

示例（MD5 签名）：

// 参数定义：text,key
const raw = text + key;
let md5 = 0;
for (let i = 0; i < raw.length; i++) {
  md5 = (md5 * 31 + raw.charCodeAt(i)) >>> 0;
}
return md5.toString(16);

三、试运行

保存前先在编辑器下方的「试运行」面板验证：

1. 在参数框填 JSON 数组，如 ["hello", "myKey"]
2. 点「运行」，查看返回结果、执行耗时和 console 日志
3. 参数个数与定义不一致时会有黄色提示

四、在哪里用、怎么用

4.1 接口参数值（最常用）

Header / Cookie / Query / Body 参数行的参数值输入框：

1. 输入 @ 或 fn. 弹出函数辅助下拉
2. 选中函数（如 @fn.请求签名(text,key)），补全参数
3. 失焦后自动保存为函数引用；引用按函数 ID 记录，函数改名不影响已有配置

API 场景的接口请求步骤参数用法相同。

4.2 Body 原始 JSON

raw JSON 中手写调用表达式：

{
  "sign": "{{__CUSTOM(5, 'hello', 'myKey')}}"
}

其中 5 是函数 ID（在函数列表「复制调用表达式」可直接拿到带 ID 的完整表达式，粘贴后改参数即可）。

4.3 前置 / 后置脚本

脚本里按名称调用（API 测试与 API 场景步骤的脚本均支持）：

const sign = fn.请求签名('hello', 'myKey');
context.setVariable('sign', sign);

也可按 ID 调用：context.utils.custom(5, 'hello', 'myKey')。

4.4 UI 场景步骤字段

UI 场景中经过变量替换的步骤字段同样支持（如打开页面的 URL、键盘输入的文本、DOM 操作的值），写法和参数值一致：@ 触发选择或手写 {{__CUSTOM(id,...)}}。

4.5 与变量嵌套

变量值里也可以放函数表达式——变量替换完成后函数仍会执行，例如全局变量 SIGN = {{__CUSTOM(5, '${uid}', 'key')}}。

五、常见问题

1. 函数改了名，引用会失效吗：不会。参数里的引用按函数 ID 存储，名称只用于展示
2. 删了函数会怎样：引用它的参数在运行时会按原样输出表达式文本，不会报错，请删除前先检查引用
3. @fn.xxx(...) 手写在 Body 里没执行：手写文本只认 {{__CUSTOM(id,...)}} 格式；@fn. 写法仅在参数输入框（有辅助下拉）和脚本（fn. 前缀）中有效