Apifox Mock Script Gen

Apifox Mock 脚本生成器

核心原则

⚠️ 无文档不生成！必须先获取 API 文档，才能编写 Mock 脚本。

反模式警示（禁止行为）

反模式1：凭经验猜测数据结构

❌ 听到"营业时间"就认为是 object {monday: "5-18"}
✅ 必须先查看文档，确认是 array 还是 object

反模式2：跳过文档获取步骤

❌ 用户描述需求后直接生成代码
✅ 必须先调用 apifox_get_api_detail 获取文档

反模式3：忽略嵌套类型

❌ 只检查顶层字段 $.data.businessHours 的类型
✅ 必须检查嵌套字段 $.data.businessHours[0].day 的类型

执行流程（强制顺序）

第一阶段：信息收集 🔴 [必须先完成]

1. 🔴 强制：调用 mcp__apifox-api-docs-mcp__apifox_get_api_list
   └─ 如果失败，停止并报错："无法获取接口列表"

2. 🔴 强制：匹配目标接口并获取 apiId
   └─ 如果找不到，停止并报错："未找到目标接口"

3. 🔴 强制：调用 mcp__apifox-api-docs-mcp__apifox_get_api_detail
   └─ 如果失败，停止并报错："无法获取接口详情"

4. 🔴 强制：提取类型定义并创建映射表
   └─ 遍历所有字段，记录路径和类型

第二阶段：需求确认（可选）

在获取文档后，向用户确认：

• [ ] 是否需要分页支持？
• [ ] 是否需要 Token 验证？
• [ ] 是否需要模拟网络延迟？
• [ ] 是否需要异常场景（404、500 等）？
• [ ] 是否需要参数校验逻辑？

第三阶段：脚本生成（基于文档）

1. 参照类型映射表生成 Mock 数据
2. 根据需求选择代码模式（见 references/code-patterns.md）
3. 为每个字段添加类型注释

第四阶段：质量验证（逐字段检查）

✓ 步骤1：验证 API 调用方式（使用 fox. 前缀）
✓ 步骤2：验证函数调用（handleRequest() 被调用）
✓ 步骤3：🔴 逐字段验证类型（对照类型映射表）
✓ 步骤4：验证嵌套类型（array 元素、object 字段）
✓ 步骤5：验证必填字段（有默认值）
✓ 步骤6：验证注释完整性

类型映射表创建流程

从 API 文档提取类型后，创建类型映射表：

// 从 API 文档提取的类型定义
var typeMapping = {
  // 基本类型
  '$.data.code': 'integer',
  '$.data.msg': 'string',
  '$..data.id': 'integer',

  // 对象类型
  '$.data.description': 'object',
  '$.data.description.title': 'string',

  // 数组类型
  '$.data.images': 'array',
  '$.data.images[0]': 'string',

  // 嵌套数组对象
  '$.data.businessHours': 'array',
  '$.data.businessHours[0]': 'object',
  '$.data.businessHours[0].day': 'integer',
  '$.data.businessHours[0].open': 'string'
};

数据类型严格匹配

硬约束（必须遵循）

1. API 调用规范

// ✅ 正确：使用 fox. API
var responseJson = fox.mockResponse.json();
fox.mockResponse.setBody(responseJson);

// ❌ 错误：使用不存在的 API
response.json(data);
res.send(data);

2. 参数获取策略

3. 函数调用要求

// ✅ 正确：定义并手动调用
var handleRequest = function() {
  // 逻辑代码
};
handleRequest();

// ❌ 错误：使用参数化函数（不会被执行）
function handleMockRequest(req, res) {
  // 逻辑代码
}

标准模板

基础结构

var MockJs = require('mockjs');

var handleRequest = function() {
  var responseJson = fox.mockResponse.json();

  // GET 请求：获取 Query 参数
  var page = fox.mockRequest.getParam('page') || '1';

  // POST 请求：获取 JSON Body
  var body = fox.mockRequest.body || {};

  responseJson.code = 0;
  responseJson.msg = 'success';
  responseJson.data = {
    page: page,
    moduleId: body.module || 1
  };

  fox.mockResponse.setBody(responseJson);
  fox.mockResponse.setDelay(300);
};

handleRequest();

质量检查清单（生成前必查）

阶段0：文档完整性检查 🔴 [前置条件]

• [ ] 已成功调用 apifox_get_api_list 并获取接口列表
• [ ] 已成功调用 apifox_get_api_detail 并获取完整文档
• [ ] 已从文档中提取所有字段的类型定义
• [ ] 已创建类型映射表（字段路径 → 类型）
• [ ] 如果以上任何一项未完成，停止生成并报错

阶段1：脚本规范检查

• [ ] 使用 fox.mockResponse.json() 获取响应对象
• [ ] 使用 fox.mockResponse.setBody() 设置响应
• [ ] 定义 handleRequest() 函数并在末尾调用
• [ ] 不使用 (req, res) 参数模式
• [ ] 所有 API 调用都使用 fox. 前缀

阶段2：数据类型检查 🔴 [核心检查]

• [ ] 顶层字段类型与文档一致
• [ ] 嵌套对象字段类型与文档一致
• [ ] 数组元素类型与文档一致
• [ ] 深层嵌套类型正确（如 $.data.items[0].user.id）
• [ ] 特殊类型正确（integer 用数字而非字符串）

阶段3：功能完整性检查

• [ ] 根据需求添加了分页逻辑
• [ ] 根据需求添加了 Token 验证
• [ ] 根据需求添加了异常场景
• [ ] 根据需求添加了延迟模拟
• [ ] 代码包含必要的注释说明

输出格式要求

// 1. 引入依赖（如需要）
var MockJs = require('mockjs');

// 2. 主处理函数
var handleRequest = function() {
  // 2.1 获取响应对象
  var responseJson = fox.mockResponse.json();

  // 2.2 获取请求参数（根据 HTTP 方法选择正确方式）
  var param = fox.mockRequest.getParam('key');  // GET
  // var body = fox.mockRequest.body.key;       // POST

  // 2.3 业务逻辑处理（分页、Token、异常等）

  // 2.4 设置响应数据
  responseJson.code = 0;
  responseJson.msg = 'success';
  responseJson.data = { /* Mock 数据 */ };

  // 2.5 返回响应
  fox.mockResponse.setBody(responseJson);
  fox.mockResponse.setDelay(500);  // 可选
};

// 3. 手动调用函数
handleRequest();

参考资源

核心文档

• 代码模式库：references/code-patterns.md - 分页、Token、异常等常见场景的代码模式
• 错误案例库：references/error-cases.md - 常见错误及解决方案
• API 参考：references/api-reference.md - 完整的 API 文档
• Mock 脚本指南：references/mock_script_guide.md - Apifox 官方文档

MCP 工具

• mcp__apifox-api-docs-mcp__apifox_get_api_list - 获取接口列表
• mcp__apifox-api-docs-mcp__apifox_get_api_detail - 获取接口详情
• mcp__apifox-api-docs-mcp__apifox_health_check - 健康检查

使用场景指南

何时读取 code-patterns.md？

• 需要实现分页逻辑时
• 需要添加 Token 验证时
• 需要模拟异常场景时
• 需要使用 Mock.js 生成随机数据时

何时读取 error-cases.md？

• 脚本不生效时
• 获取不到参数时
• 出现类型错误时
• 遇到语法错误时

何时读取 api-reference.md？

• 不确定使用哪个 API 时
• 需要查询 API 参数时
• 需要了解数据类型映射时
• 需要查看完整示例时

Apifox Mock API 快速参考

本文件提供 Apifox Mock 自定义脚本的完整 API 参考。在需要查询具体 API 用法时参考此文件。

目录

1. 请求对象 API 2. 响应对象 API 3. Headers 对象 API 4. RequestBody 对象 API 5. Cookies 对象 API 6. 参数获取策略矩阵 7. 数据类型映射表

请求对象 API

fox.mockRequest

请求对象的入口点，提供访问请求参数、Headers、Cookies 等功能。

headers

类型：Headers

说明：请求的 HTTP 头对象

示例：

var token = fox.mockRequest.headers.get('token');
var contentType = fox.mockRequest.headers.get('Content-Type');

cookies

类型：Cookies

说明：请求带的 Cookies 对象

示例：

var sessionId = fox.mockRequest.cookies.get('sessionId');
var userToken = fox.mockRequest.cookies.get('userToken');

body

类型：RequestBody

说明：请求 Body 对象（Postman 兼容）

示例：

var username = fox.mockRequest.body.username;
var userId = fox.mockRequest.body.user.id;
var firstItem = fox.mockRequest.body.items[0];

getParam(key)

类型：(key: string) => string

说明：获取请求参数，包括 Path 参数、Body 参数、Query 参数

示例：

var page = fox.mockRequest.getParam('page');
var pageSize = fox.mockRequest.getParam('pageSize');
var keyword = fox.mockRequest.getParam('keyword');

响应对象 API

fox.mockResponse

响应对象的入口点，提供设置响应数据、状态码、延迟等功能。

headers

类型：Headers

说明：响应的 HTTP 头对象

示例：

fox.mockResponse.headers.add({
  key: 'X-Token',
  value: '<token>'
});

code

类型：number

说明：系统自动生成的 HTTP 状态码

示例：

var currentCode = fox.mockResponse.code;

json()

类型：() => any

说明：获取系统自动生成的 JSON 格式响应数据

示例：

var responseJson = fox.mockResponse.json();
responseJson.code = 0;
responseJson.msg = 'success';
responseJson.data = {};

setBody(body)

类型：(body: any) => void

说明：设置接口返回 Body，参数支持 JSON 或字符串

示例：

// JSON 格式
fox.mockResponse.setBody({
  code: 0,
  msg: 'success',
  data: {}
});

// 字符串格式
fox.mockResponse.setBody('Hello World!');

setCode(code)

类型：(code: number) => void

说明：设置接口返回的 HTTP 状态码

示例：

fox.mockResponse.setCode(200);
fox.mockResponse.setCode(404);
fox.mockResponse.setCode(500);

setDelay(duration)

类型：(duration: number) => void

说明：设置 Mock 响应延时，单位为毫秒

示例：

fox.mockResponse.setDelay(500);   // 500ms
fox.mockResponse.setDelay(2000);  // 2秒

Headers 对象 API

Headers 对象用于操作 HTTP 头，既可用于请求对象也可用于响应对象。

get(key)

类型：(key: string) => string

说明：获取指定 Header 的值

示例：

var token = fox.mockRequest.headers.get('token');
var auth = fox.mockRequest.headers.get('Authorization');

add(options)

类型：(options: { key: string, value: string }) => void

说明：添加 Header（如已存在则报错）

示例：

fox.mockResponse.headers.add({
  key: 'X-Custom-Header',
  value: 'custom-value'
});

upsert(options)

类型：(options: { key: string, value: string }) => void

说明：添加或修改 Header（不存在则新增，已存在则修改）

示例：

fox.mockResponse.headers.upsert({
  key: 'X-Token',
  value: '<token>'
});

remove(key)

类型：(key: string) => void

说明：删除指定 Header

示例：

fox.mockResponse.headers.remove('X-Old-Header');

RequestBody 对象 API（Postman 兼容）

RequestBody 对象提供多种方式访问请求 Body 内容。

toJSON()

类型：() => object

说明：获取请求 JSON 格式的 Body 内容

示例：

var jsonData = fox.mockRequest.body.toJSON();
var username = jsonData.username;

toString()

类型：() => string

说明：获取请求 string 格式的 Body 内容

示例：

var stringData = fox.mockRequest.body.toString();

formdata.get(key)

类型：(key: string) => string

说明：获取请求 form-data 格式的 Body 内容

示例：

var userId = fox.mockRequest.body.formdata.get('userId');
var file = fox.mockRequest.body.formdata.get('file');

urlencoded.get(key)

类型：(key: string) => string

说明：获取请求 urlencoded 格式的 Body 内容

示例：

var username = fox.mockRequest.body.urlencoded.get('username');
var password = fox.mockRequest.body.urlencoded.get('password');

Cookies 对象 API

Cookies 对象用于访问请求中的 Cookie。

get(key)

类型：(key: string) => string

说明：获取指定 Cookie 的值

示例：

var sessionId = fox.mockRequest.cookies.get('sessionId');
var userToken = fox.mockRequest.cookies.get('userToken');

参数获取策略矩阵

根据 HTTP 方法和参数位置选择正确的 API：

数据类型映射表

从 API 文档提取类型后，使用对应的 Mock 数据生成策略：

类型验证技巧

使用以下方法验证数据类型：

// 基本类型检查
typeof value === 'string'           // 字符串
typeof value === 'number'           // 数字（包括 integer 和 float）
Number.isInteger(value)             // 整数
typeof value === 'boolean'          // 布尔值

// 复杂类型检查
Array.isArray(value)                // 数组
typeof value === 'object' && value !== null  // 对象
value === null                      // null

完整示例

GET 请求示例

var handleRequest = function() {
  var responseJson = fox.mockResponse.json();

  // 获取 Query 参数
  var page = parseInt(fox.mockRequest.getParam('page')) || 1;
  var pageSize = parseInt(fox.mockRequest.getParam('pageSize')) || 10;

  // 获取 Headers
  var token = fox.mockRequest.headers.get('token');

  // 设置响应
  responseJson.code = 0;
  responseJson.msg = 'success';
  responseJson.data = {
    page: page,
    pageSize: pageSize,
    total: 100,
    list: []
  };

  fox.mockResponse.setBody(responseJson);
  fox.mockResponse.setDelay(500);
};

handleRequest();

POST 请求示例

var handleRequest = function() {
  var responseJson = fox.mockResponse.json();

  // 获取 JSON Body
  var username = fox.mockRequest.body.username;
  var password = fox.mockRequest.body.password;

  // 参数验证
  if (!username || !password) {
    responseJson.code = 400;
    responseJson.msg = '用户名和密码不能为空';
    fox.mockResponse.setBody(responseJson);
    fox.mockResponse.setCode(400);
    return;
  }

  // 设置响应
  responseJson.code = 0;
  responseJson.msg = '登录成功';
  responseJson.data = {
    token: 'mock-token-123',
    userId: 1001
  };

  fox.mockResponse.setBody(responseJson);
};

handleRequest();

重要说明

Mock 优先级

请求 Mock 数据时，规则匹配优先级为：高级 Mock 里的期望 > 自定义 Mock 脚本。如果匹配到了高级 Mock 里的期望，则不调用自定义 Mock 脚本。

使用限制

1. 此脚本仅用于「高级 Mock」的「Mock 自定义脚本」，不能用于前后置脚本中 2. 需要在接口设置中先开启此功能才能使用 3. 支持使用 require 引入 Mock.js 等依赖库

兼容性说明

Apifox 提供两套 API 语法：

• fox 前缀：Apifox 原生 API（推荐使用）
• $$ 前缀：兼容 Postman pm.request/pm.response 语法的 API

两套 API 功能等价，开发者可根据习惯选择使用。

Postman 语法示例

// 获取自动 Mock 出来的数据
var responseJson = $$.mockResponse.json();

// 修改 responseJson 里的分页数据
responseJson.page = $$.mockRequest.getParam("page");
responseJson.total = 120;

// 将修改后的 json 写入 $$.mockResponse
$$.mockResponse.setBody(responseJson);

// 获取请求参数
var userId = $$.mockRequest.getParam("userId");

// 获取请求 Header
var userId = $$.mockRequest.headers.get("userId");

// 获取请求 Cookie
var userId = $$.mockRequest.cookies.get("userId");

// 设置接口返回的 HTTP 状态码
$$.mockResponse.setCode(200);

// 设置 Mock 响应延时，单位为毫秒
$$.mockResponse.setDelay(3000);

Apifox Mock 代码模式库

本文件包含各种常见场景的 Mock 脚本代码模式。在需要生成特定功能的 Mock 脚本时参考这些模式。

目录

1. 基础结构 2. 分页数据处理 3. Token 验证 4. Mock.js 随机数据 5. 异常场景模拟 6. 网络延迟模拟 7. 参数校验逻辑

基础结构

适用于所有 Mock 脚本的基础模板。

var MockJs = require('mockjs');

var handleRequest = function() {
  var responseJson = fox.mockResponse.json();

  // GET 请求：获取 Query 参数
  var page = fox.mockRequest.getParam('page') || '1';

  // POST 请求：获取 JSON Body
  var body = fox.mockRequest.body || {};

  responseJson.code = 0;
  responseJson.msg = 'success';
  responseJson.data = {
    page: page,
    moduleId: body.module || 1
  };

  fox.mockResponse.setBody(responseJson);
  fox.mockResponse.setDelay(300);
};

handleRequest();

分页数据处理

适用于需要分页的列表接口。

var MockJs = require('mockjs');

var handleRequest = function() {
  var responseJson = fox.mockResponse.json();

  // 获取分页参数
  var page = parseInt(fox.mockRequest.getParam('page')) || 1;
  var pageSize = parseInt(fox.mockRequest.getParam('pageSize')) || 10;

  // 生成分页数据
  responseJson.code = 0;
  responseJson.msg = 'success';
  responseJson.data = {
    page: page,
    pageSize: pageSize,
    total: 120,
    list: MockJs.mock({
      'list|10': [{
        'id|+1': (page - 1) * pageSize + 1,
        name: '@cname',
        email: '@email'
      }]
    }).list
  };

  fox.mockResponse.setBody(responseJson);
  fox.mockResponse.setDelay(300);
};

handleRequest();

Token 验证

适用于需要身份验证的接口。

var handleRequest = function() {
  var responseJson = fox.mockResponse.json();

  // 验证 Token
  var token = fox.mockRequest.headers.get('token');
  if (!token) {
    responseJson.code = 401;
    responseJson.msg = '未授权：缺少 Token';
    fox.mockResponse.setBody(responseJson);
    fox.mockResponse.setCode(401);
    return;
  }

  // Token 验证通过
  responseJson.code = 0;
  responseJson.msg = 'success';
  responseJson.data = {
    userId: 1001,
    username: 'test_user'
  };

  fox.mockResponse.setBody(responseJson);
};

handleRequest();

Mock.js 随机数据

适用于需要生成大量测试数据的场景。

var MockJs = require('mockjs');

var handleRequest = function() {
  var responseJson = fox.mockResponse.json();

  responseJson.code = 0;
  responseJson.msg = 'success';
  responseJson.data = MockJs.mock({
    // 用户列表
    'list|5-10': [{
      'id|+1': 1,
      name: '@cname',           // 中文姓名
      email: '@email',           // 邮箱
      phone: /^1[3-9]\d{9}$/,   // 手机号
      avatar: '@image("100x100")', // 头像
      address: '@city(true)',    // 地址
      createTime: '@datetime("yyyy-MM-dd HH:mm:ss")'
    }],
    // 统计数据
    stats: {
      'total|100-1000': 1,
      'active|50-500': 1,
      'rate|1-100': 1
    }
  });

  fox.mockResponse.setBody(responseJson);
};

handleRequest();

异常场景模拟

适用于需要测试各种错误情况的场景。

var handleRequest = function() {
  var responseJson = fox.mockResponse.json();

  // 获取参数
  var id = fox.mockRequest.getParam('id');

  // 异常场景1：资源不存在
  if (id === '999') {
    responseJson.code = 404;
    responseJson.msg = '资源不存在';
    fox.mockResponse.setBody(responseJson);
    fox.mockResponse.setCode(404);
    return;
  }

  // 异常场景2：服务器错误
  if (id === '500') {
    responseJson.code = 500;
    responseJson.msg = '服务器内部错误';
    fox.mockResponse.setBody(responseJson);
    fox.mockResponse.setCode(500);
    return;
  }

  // 正常响应
  responseJson.code = 0;
  responseJson.msg = 'success';
  responseJson.data = { id: id, name: '测试数据' };
  fox.mockResponse.setBody(responseJson);
};

handleRequest();

网络延迟模拟

适用于需要测试加载状态的场景。

var handleRequest = function() {
  var responseJson = fox.mockResponse.json();

  // 模拟不同的延迟场景
  var delayType = fox.mockRequest.getParam('delay');

  if (delayType === 'slow') {
    fox.mockResponse.setDelay(2000); // 慢速：2秒
  } else if (delayType === 'fast') {
    fox.mockResponse.setDelay(100);  // 快速：100ms
  } else {
    fox.mockResponse.setDelay(500);  // 正常：500ms
  }

  responseJson.code = 0;
  responseJson.msg = 'success';
  responseJson.data = { message: '请求成功' };

  fox.mockResponse.setBody(responseJson);
};

handleRequest();

参数校验逻辑

适用于需要验证请求参数的场景。

var handleRequest = function() {
  var responseJson = fox.mockResponse.json();

  // 获取参数
  var email = fox.mockRequest.getParam('email');
  var phone = fox.mockRequest.getParam('phone');

  // 校验邮箱格式
  var emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!email || !emailRegex.test(email)) {
    responseJson.code = 400;
    responseJson.msg = '邮箱格式不正确';
    fox.mockResponse.setBody(responseJson);
    fox.mockResponse.setCode(400);
    return;
  }

  // 校验手机号格式
  var phoneRegex = /^1[3-9]\d{9}$/;
  if (!phone || !phoneRegex.test(phone)) {
    responseJson.code = 400;
    responseJson.msg = '手机号格式不正确';
    fox.mockResponse.setBody(responseJson);
    fox.mockResponse.setCode(400);
    return;
  }

  // 校验通过
  responseJson.code = 0;
  responseJson.msg = 'success';
  responseJson.data = {
    email: email,
    phone: phone
  };

  fox.mockResponse.setBody(responseJson);
};

handleRequest();

Mock.js 常用方法速查

基础数据类型

'@string'           // 随机字符串
'@integer'          // 随机整数
'@float'            // 随机浮点数
'@boolean'          // 随机布尔值

个人信息

'@cname'            // 中文姓名
'@name'             // 英文姓名
'@email'            // 邮箱
'@phone'            // 手机号
'@id'               // 身份证号
'@ip'               // IP 地址

地址和位置

'@city(true)'       // 带省份的城市
'@county(true)'     // 带城市的区县
'@address'          // 完整地址
'@zip'              // 邮政编码

时间和日期

'@datetime'         // 完整日期时间
'@date'             // 日期
'@time'             // 时间
'@datetime("yyyy-MM-dd HH:mm:ss")'  // 自定义格式

图片和颜色

'@image("200x100")' // 指定尺寸图片
'@color'            // 随机颜色
'@rgb'              // RGB 颜色

文本内容

'@ctitle'           // 中文标题
'@cparagraph'       // 中文段落
'@csentence'        // 中文句子
'@cword'            // 中文单词

数组操作

'list|10'           // 固定10个元素
'list|5-10'         // 5-10个随机元素
'id|+1'             // 自增ID

Apifox Mock 错误案例库

本文件收录了常见的 Mock 脚本错误案例及其正确解决方案。在遇到问题时参考这些案例可以快速定位和修复问题。

目录

1. 错误 #1：脚本不生效 2. 错误 #2：POST Body 参数获取错误 3. 错误 #3：Mock.js 字符串拼接 4. 错误 #4：全局作用域 return 5. 错误 #5：数据类型不匹配 6. 错误 #6：嵌套类型不匹配 7. 错误 #7：深层嵌套类型错误

错误 #1：脚本不生效 ⚠️ 最高频错误

症状：脚本保存后没有任何效果

错误代码

// ❌ 错误：使用参数化函数（不会被执行）
function handleMockRequest(req, res) {
  var responseJson = fox.mockResponse.json();
  responseJson.code = 0;
  res.json(responseJson);  // 方法不存在
  return responseJson;     // return 无效
}

正确代码

// ✅ 正确：定义并手动调用
var handleRequest = function() {
  var responseJson = fox.mockResponse.json();
  responseJson.code = 0;
  fox.mockResponse.setBody(responseJson);
};

handleRequest();  // 必须手动调用

问题分析

1. Apifox 不会自动调用带参数的函数 2. 必须使用 var 声明函数表达式 3. 必须在脚本末尾手动调用该函数 4. 不能使用 res.json() 等不存在的方法

错误 #2：POST Body 参数获取错误

症状：获取不到 POST 请求的参数

错误代码

// ❌ 错误1：方法不存在
var body = fox.mockRequest.getJson();

// ❌ 错误2：嵌套路径访问
var module = fox.mockRequest.getParam('body.module');

正确代码

// ✅ 正确：直接访问 body 对象
var body = fox.mockRequest.body || {};
var module = body.module || 1;

问题分析

1. POST/PUT 请求的 JSON Body 通过 fox.mockRequest.body 访问 2. Body 是一个对象，可以直接通过点号访问属性 3. 不要使用 getParam() 访问 Body 内容

错误 #3：Mock.js 字符串拼接

症状：语法错误或数据不生成

错误代码

// ❌ 错误：使用字符串拼接
var data = MockJs.mock('@pick(' + JSON.stringify(arr) + ')');

正确代码

// ✅ 正确：使用原生 JavaScript
var data = arr[Math.floor(Math.random() * arr.length)];

问题分析

1. Mock.js 的占位符不支持动态参数拼接 2. 对于简单随机选择，使用原生 JavaScript 更可靠 3. 复杂场景可以考虑使用 Mock.js 的其他占位符

错误 #4：全局作用域 return

症状：报错 "Illegal return statement"

错误代码

// ❌ 错误：return 在全局作用域
var token = fox.mockRequest.headers.get('token');
if (!token) {
  responseJson.code = 401;
  fox.mockResponse.setBody(responseJson);
  return;  // 非法！
}

正确代码

// ✅ 正确：包装在函数中
var handleRequest = function() {
  var token = fox.mockRequest.headers.get('token');
  if (!token) {
    responseJson.code = 401;
    fox.mockResponse.setBody(responseJson);
    return;  // 在函数中合法
  }
  // 其他逻辑...
};
handleRequest();

问题分析

1. JavaScript 不能在全局作用域使用 return 2. 所有逻辑必须包装在函数中 3. return 只能在函数内部使用

错误 #5：数据类型不匹配

症状：前端报类型错误

错误示例

// ❌ 文档定义 businessHours 为 object，但生成 array
responseJson.data.businessHours = [];

// ❌ 文档定义 day 为 integer，但生成 string
responseJson.data.day = '周一';

// ✅ 正确
responseJson.data.businessHours = { open: '09:00', close: '18:00' };
responseJson.data.day = 1;

问题分析

1. 必须严格按照 API 文档的类型定义生成数据 2. 常见类型错误：

• object → [] （应该是 {}）
• string → 123 （应该是 '123'）
• integer → '123' （应该是 123）

预防措施

// 从 API 文档提取类型定义
// $.data.businessHours: object
// $.data.day: integer

// 创建类型映射表
var typeMapping = {
  'businessHours': 'object',
  'day': 'integer'
};

// 按类型生成数据
responseJson.data.businessHours = { open: '09:00', close: '18:00' };
responseJson.data.day = 1;

错误 #6：嵌套类型不匹配 ⚠️ 高频错误

症状：类型检查工具报错，如 $.data.businessHours 应当是 array 类型

真实案例

// ❌ 错误：根据业务习惯假设结构，未查看文档
responseJson.data.businessHours = {
  monday: '05:00-18:00',
  tuesday: '06:00-09:00'
};

// ✅ 正确：按文档定义为 array
responseJson.data.businessHours = [
  { day: 1, open: '05:00', close: '18:00' },
  { day: 2, open: '06:00', close: '09:00' }
];

错误根源

1. 未获取 API 文档，凭经验假设数据结构 2. 忽略了嵌套字段的类型定义 3. 未进行逐字段类型核对

预防措施

// 步骤1：从文档提取类型定义
// $.data.businessHours: array[object]
// $.data.businessHours[0].day: integer
// $.data.businessHours[0].open: string

// 步骤2：创建类型映射表
var typeMapping = {
  'businessHours': 'array',
  'businessHours[].day': 'integer',
  'businessHours[].open': 'string'
};

// 步骤3：按类型生成数据
responseJson.data.businessHours = [
  { day: 1, open: '05:00', close: '18:00' }  // day 是 integer
];

错误 #7：深层嵌套类型错误

症状：用户反馈 $.data.businessHours[0].day 应当是 integer 类型

错误示例

// ❌ 错误：使用字符串表示星期
responseJson.data.businessHours = [
  { day: 'monday', open: '05:00', close: '18:00' },
  { day: 'tuesday', open: '06:00', close: '09:00' }
];

// ✅ 正确：使用整数表示星期
responseJson.data.businessHours = [
  { day: 1, open: '05:00', close: '18:00' },
  { day: 2, open: '06:00', close: '09:00' }
];

类型对照表

完整验证流程

// 步骤1：从 API 文档提取类型定义
// 步骤2：创建类型映射表（包含嵌套字段）
// 步骤3：根据类型选择对应的 Mock 规则
// 步骤4：生成代码后逐字段核对
// 步骤5：检查嵌套类型（array 元素、object 字段）
// 步骤6：验证输出代码的类型一致性

类型错误典型案例

案例1：资源详情接口类型错误

场景：生成资源详情 Mock 脚本

错误过程：

第1轮：用户描述需求
  → businessHours: "周一是5-18，周二是6到9点"
  → AI 理解为 object 类型 {monday: "5-18"}

第2轮：用户纠正
  → "$.data.businessHours 应当是 array 类型"
  → AI 修改为 array [{day: "monday"}]

第3轮：用户再次纠正
  → "$.data.businessHours[0].day 应当是 integer 类型"
  → AI 最终修改为 [{day: 1}]

正确流程（避免3次修正）：

步骤1：获取 API 文档（获取真实的类型定义）
步骤2：提取类型映射表
  {
    "businessHours": "array",
    "businessHours[].day": "integer",
    "description": "object"
  }
步骤3：按类型生成 Mock 数据
步骤4：逐字段验证类型

教训：如果一开始就获取文档，可以避免 100% 的类型错误。

快速故障排除

问题：脚本不生效

检查清单：

• [ ] 使用了 var handleRequest = function() {} 而不是 function handleRequest()
• [ ] 在脚本末尾调用了 handleRequest()
• [ ] 没有使用 (req, res) 参数
• [ ] 使用了 fox.mockResponse.setBody() 而不是 res.json()

问题：获取不到参数

检查清单：

• [ ] GET 请求使用 fox.mockRequest.getParam(key)
• [ ] POST 请求使用 fox.mockRequest.body.key
• [ ] Headers 使用 fox.mockRequest.headers.get(key)
• [ ] 参数名称拼写正确

问题：类型错误

检查清单：

• [ ] 已获取 API 文档
• [ ] 创建了类型映射表
• [ ] 逐字段验证了类型
• [ ] 检查了嵌套字段的类型
• [ ] integer 使用数字而不是字符串
• [ ] array 使用 [] 而不是 {}
• [ ] object 使用 {} 而不是 []

Apifox Mock 自定义脚本文档

引用方式

在 Apifox 接口的「高级 Mock」设置中使用 Mock 自定义脚本功能

功能类型

工具

功能名称

Mock 自定义脚本

功能描述

Apifox Mock 自定义脚本允许开发者通过 JavaScript 代码动态控制 Mock 接口的响应行为。该功能提供了灵活的请求参数获取和响应内容修改能力，支持根据请求参数、Headers、Cookies 等条件动态生成响应数据。适用于需要复杂 Mock 逻辑的场景，如分页数据模拟、权限验证、异常场景测试等。

何时使用

• 需要根据请求参数动态生成 Mock 数据时
• 需要模拟权限验证和异常响应时
• 需要测试分页、延迟等特殊场景时
• 需要基于请求头或 Cookie 返回不同数据时
• 需要完全自定义响应逻辑时

使用示例

基础示例：分页数据设置

// 获取智能 Mock 功能自动 Mock 出来的数据
var responseJson = fox.mockResponse.json();

// 修改 responseJson 里的分页数据
// 将 page 设置为请求参数的 page
responseJson.page = parseInt(fox.mockRequest.getParam('page'));
// 将 total 设置 120
responseJson.total = 120;

// 将修改后的 json 写入 fox.mockResponse
fox.mockResponse.setBody(responseJson);

高级示例：多条件判断与动态响应

var MockJs = require('mockjs');

// 获取"智能Mock"自动生成的 json
var responseJson = fox.mockResponse.json();

// 根据请求参数（包括 query、body、path）修改响应值
if(fox.mockRequest.getParam('id') === '123'){
  responseJson.data = null;
  responseJson.code = 400104;
  responseJson.errorMessage = '数据不存在';
  fox.mockResponse.setBody(responseJson);
  fox.mockResponse.setCode(404);
}

// 根据请求的 header 修改响应值
if(!fox.mockRequest.headers.get('token')){
  responseJson.data = null;
  responseJson.code = 400103;
  responseJson.errorMessage = '没有权限';
  fox.mockResponse.setBody(responseJson);
  fox.mockResponse.setCode(403);
}

// 根据请求的 cookie 修改响应值
if(fox.mockRequest.cookies.get('projectId') === '123'){
    var idList = [1,2,3,4,5,6,7,8];
    fox.mockResponse.setBody({
        code: 0,
        data: idList.map(function(id){
            return {
                id: id,
                name: MockJs.mock('@cname'),
                email: MockJs.mock('@email'),
                city: MockJs.mock('@city'),
            }
        })
    });
}

// 设置返回延迟
fox.mockResponse.setDelay(500);

// 添加 header
fox.mockResponse.headers.add({
    key: 'X-Token',
    value: '<token>',
});

// 添加或修改 header
fox.mockResponse.headers.upsert({
    key: 'X-Token',
    value: '<token>',
});

兼容 Postman 语法示例

// 获取自动 Mock 出来的数据
var responseJson = $$.mockResponse.json();
// 修改 responseJson 里的分页数据
// 将 page 设置为请求参数的 page
responseJson.page = $$.mockRequest.getParam("page");
// 将 total 设置 120
responseJson.total = 120;
// 将修改后的 json 写入 $$.mockResponse
$$.mockResponse.setBody(responseJson);

// 获取请求参数
var userId = $$.mockRequest.getParam("userId");
// 获取请求 Header
var userId = $$.mockRequest.headers.get("userId");
// 获取请求 Cookie
var userId = $$.mockRequest.cookies.get("userId");
// 获取请求 JSON 格式的 Body 内容
var requestJsonData = $$.mockRequest.body.toJSON();
// 获取请求 string 格式的 Body 内容
var requestStringData = $$.mockRequest.body.toString();
// 获取请求 form-data 格式的 Body 内容
var userId = $$.mockRequest.body.formdata.get("userId");
// 获取请求 urlencoded 格式的 Body 内容
var userId = $$.mockRequest.body.urlencoded.get("userId");

// 获取系统自动生成的 JSON 格式响应数据
var responseJsonData = $$.mockResponse.json();
// 设置接口返回 JSON 格式 Body
$$.mockResponse.setBody({ id: "1", name: "Apple" });
// 设置接口返回 string 格式 Body
$$.mockResponse.setBody("Hello World!");
// 设置接口返回的 HTTP 状态码
$$.mockResponse.setCode(200);
// 设置 Mock 响应延时，单位为毫秒
$$.mockResponse.setDelay(3000);
// 获取 HTTP 状态码
var statusCode = $$.mockResponse.code;
// 获取 HTTP header
var myHeader = $$.mockResponse.headers.get("X-My-Header");
// 删除当前请求里 key 为 X-My-Header 的 header
$$.mockResponse.headers.remove("X-My-Header")
// 给当前请求添加一个 key 为 X-My-Header 的 header。
$$.mockResponse.headers.add({ key: "X-My-Header", value: "hello"});
// upsert key 为 X-My-Header 的 header（如不存在则新增,如已存在则修改）。
$$.mockResponse.headers.upsert({ key: "X-My-Header", value: "hello"})

API

请求对象 API

响应对象 API

Headers 对象 API

RequestBody 对象 API（Postman 兼容）

Cookies 对象 API

类型描述

本工具为 JavaScript 运行时环境,无静态类型定义。主要类型如下：

重要说明

Mock 优先级

请求 Mock 数据时,规则匹配优先级为：高级 Mock 里的期望 > 自定义 Mock 脚本。如果匹配到了高级 Mock 里的期望,则不调用自定义 Mock 脚本。

使用限制

1. 此脚本仅用于「高级 Mock」的「Mock 自定义脚本」,不能用于前后置脚本中 2. 需要在接口设置中先开启此功能才能使用 3. 支持使用 require 引入 Mock.js 等依赖库

兼容性说明

Apifox 提供两套 API 语法：

• fox 前缀：Apifox 原生 API（推荐使用）
• $$ 前缀：兼容 Postman pm.request/pm.response 语法的 API

两套 API 功能等价,开发者可根据习惯选择使用。