Apifox如何返回条件Mock数据与自定义规则设置教程

时间：2026-08-14 22:47

智能 Mock 可以让你在几秒内快速生成一个可用的模拟 API。它会读取接口数据模型，并自动返回看起来真实、结构合理的数据，例如格式正确的邮箱地址、可信的 timestamp，以及不再是 xJ8kQ 这类毫无意义的随机名称。对于绝大多数前端开发与联调场景来说，这已经足够帮助你迅速推进工作。但很快，你

智能 Mock 可以让你在几秒内快速生成一个可用的模拟 API。它会读取接口数据模型，并自动返回看起来真实、结构合理的数据，例如格式正确的邮箱地址、可信的 timestamp，以及不再是 xJ8kQ 这类毫无意义的随机名称。对于绝大多数前端开发与联调场景来说，这已经足够帮助你迅速推进工作。

但很快，你就会遇到智能 Mock 无法覆盖的业务场景。例如，你希望 /login 接口在识别到已知用户时返回 200，否则返回 401；你希望 /orders/{id} 接口对某个指定 ID 返回“已发货”的订单，而对另一个 ID 返回“已取消”的订单；你可能还需要按需强制返回 500 错误，以便在正式发布前验证前端的异常处理逻辑。问题在于，智能 Mock 对单个接口通常只能生成一种响应结构，无法根据请求内容做分支判断。而这正是本文要帮你解决的重点。

Apifox 通过两项能力解决这个问题：一是基于规则条件返回不同结果的 mock 期望，二是用于处理更复杂逻辑的 mock 脚本。本教程会结合实际示例，演示这两种方式的使用方法，并说明它们的优先级规则，确保你的自定义返回始终能够覆盖智能 Mock。如果你还不了解基础概念，可以先阅读“API mocking 概览”作为入门；本文全程使用的工具是 Apifox，而 OpenAPI 规范（OpenAPI Initiative）则定义了支撑这一切的 contract-first 设计优先工作流。

什么是条件 mock

条件 Mock 本质上就是一条规则：当传入请求满足 某种特征 时，就返回 指定的响应。Apifox 从两个层级支持这类规则配置。

第一层是接口数据模型内部的字段级自定义。你可以把某个字段固定成指定值，也可以添加动态的 Faker.js 表达式，让它在每次调用时自动变化。这一层决定的是 字段内容如何生成，但接口整体返回的响应结构仍然只有一种。

第二层是完整的响应 mock 期望。一个期望就是一条带名称的规则，包含可选的触发条件，以及独立的响应 body、状态码和 header。没有设置条件的期望会直接无条件返回固定数据；设置了条件的期望则只有在请求命中规则时才会生效。通过叠加多个期望，你就可以实现真正的条件分支 Mock：当请求满足条件 A 时返回响应 B，在缺少某个 header 时返回错误 body，或者根据不同 path 参数返回不同 payload。

正是这第二层能力，使你可以按需模拟错误状态、根据请求内容返回不同 body，并构建更接近真实后端行为的 API Mock。接下来的重点也将围绕这一层展开。

首先了解字段级动态值

在进入分支逻辑之前，先了解单个字段是如何生成动态值的会更容易上手，因为后面的条件响应也会复用相同的语法体系。

在接口数据模型中，任何字符串字段都可以写入形如 {{$category.method}} 的 Faker.js 表达式。Apifox 会在每次调用 Mock 接口时，结合你的 JSON Schema 字段类型重新解析这些表达式。

{ "id": "{{$number.int(min=1000,max=9999)}}", "customer": "{{$person.fullName}}", "email": "{{$internet.email}}", "product": "{{$commerce.productName}}", "shippingAddress": "{{$location.streetAddress}}, {{$location.city}}", "orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}" }

参数化方法同样支持，因此 {{$number.int(min=1000,max=9999)}} 可以限制数值范围，而 {{$date.between(...)}} 则可以约束日期区间和输出格式。你还可以在同一个字段中组合静态文本与多个表达式，上面的地址字段就是这样拼接生成的。如果你需要特定地区的数据风格，Apifox 还支持自定义 mock 语言环境（locales），让姓名、地址、电话号码等内容与特定国家或语言保持一致。完整方法列表可以查看 Apifox 中的 Faker.js 参考文档。

如何在 Apifox 中返回条件 Mock 数据（自定义规则与 Mock 脚本）

保存即可。默认的 HTTP 状态码为 200，因此对于正常返回流程，通常不需要再修改其他设置。

添加失败时的 mock 期望

再次点击新建期望。将其命名为 login-failure，并保持条件为空，让它充当兜底规则（catch-all）。然后将其响应数据设置为以下错误 body：

json { "error": "invalid_credentials", "message": "Username or password is incorrect." }

这个期望需要返回非默认状态码。打开该期望的 More 标签页，将 HTTP Status Code 设置为 401。顺便一提，More 标签页也是配置 Response Delay（单位毫秒，默认值为 0）以及自定义响应 header 的位置。比如设置 400ms 延迟，就是一种非常实用的方法，可以帮助你确认加载动画（loading spinner）是否真的正常渲染。

顺序至关重要

mock 期望会按照从上到下的顺序依次评估，第一个命中的规则立即生效。因此，login-success 必须放在 login-failure 上方。当请求中的 username 等于 alice@example.com 时，会先匹配成功规则并返回 Token；其他情况则会落入无条件失败规则，返回 401。如果你把顺序写反了，空白条件的兜底规则会先匹配所有请求，导致成功场景永远不会触发。

复制接口的 mock URL 后，可以测试以下两个请求路径：

# 已知用户 -> 返回 200 及 Tokencurl -X POST https:///login -H "Content-Type: application/json" -d '{"username":"alice@example.com","password":"whatever"}'# 其他任何人 -> 返回 401curl -X POST https:///login -H "Content-Type: application/json" -d '{"username":"stranger@example.com","password":"whatever"}'

实战演练：根据状态为 /orders/{id} 返回不同的 body

第二个非常常见的用法，是根据 path 参数进行条件分支。你希望 /orders/{id} 针对一个特定 ID 返回已发货订单，而针对另一个 ID 返回已取消订单，这样即使没有真实后端，前端 UI 也能完整渲染各种业务状态。

为每种状态分别创建一个 mock 期望，并为每个期望添加 path 参数 id 条件，再填写对应的 Response data。

mock 期望 order-shipped，条件：path 参数 id 等于 5001。

{"id": 5001,"status": "shipped","total": 129.90,"trackingNumber": "1Z{{$string.alphanumeric(length=16)}}","shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"}

mock 期望 order-cancelled，条件：path 参数 id 等于 5002。

{"id": 5002,"status": "cancelled","total": 0,"cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}","refundIssued": true}

最后再添加一个不带任何条件的 mock 期望，返回一个通用的待处理订单。这样即使传入其他 ID，也仍然能够得到有效响应，而不是直接失配。记得把具体规则放在兜底规则上方。保存之后，你就得到了一套可以按需渲染多种订单状态的条件 Mock。你还可以混合使用多个条件：例如在 path 条件旁边再加一个 header 条件，两者必须同时成立，因为 Apifox 会用 AND 逻辑组合多个条件，也就是文档中所说的“条件交集”。

条件并不仅限于 body 和 path。你还可以匹配 query 参数、header、cookie，甚至 IP 地址，这让你能够在测试阶段将特定响应精确限制到某个客户端或调用来源。

按需强制触发错误状态

你并不需要一个真的宕机后端，才能测试异常返回。通过一个 mock 期望配合 More 标签页，你就可以主动构造任何需要的错误状态码。

例如，要强制返回 500，你可以新增一个 mock 期望，并让客户端通过条件触发它，比如 header X-Mock-Scenario 等于 server-error。然后在 More 标签页中把 Response data 设置为真实的错误 body，再把 HTTP Status Code 设置为 500。

{"error": "internal_error","requestId": "{{$string.uuid}}","message": "Something went wrong on our end. Please retry."}

这样一来，同一个接口默认仍然返回正常的 200，而当你发送指定 header 时，它就会切换为 500。同样的思路也可以用于模拟 404、429（可在 More 标签页中设置 Retry-After header）或 503。这样，你的前端错误处理逻辑终于有了真实可测的返回数据。如果你还要在自动化测试中对这些异常响应做断言，那么 API 断言指南会与这类配置非常匹配。

对于共享项目，还有一个值得注意的细节：在 mock 期望列表中，你可以分别针对本地 Mock 和云端 Mock 环境，独立启用或关闭每条 mock 期望。因此，你可以在本地保留 500 规则用于调试，而在团队共享的云端 Mock 中将它关闭。

当规则不够用时：mock 脚本

mock 期望是声明式配置。它们擅长做匹配和返回，但不负责计算。当你需要根据请求动态生成字段、计算订单明细总额，或者让 body 结构随着多个输入参数一起变化时，就需要使用 mock 脚本。

mock 脚本是运行在 mock 响应阶段的 Ja vaScript，位置在 Mock 标签页底部的 Mock Script 区域，并可通过开关启用。这个脚本提供了两个全局变量：

$$.mockRequest：用于读取请求内容，可通过 getParam(key) 获取参数，也可访问 headers、cookies、body、formdata 和 urlencoded。
$$.mockResponse：用于构建响应，可通过 setBody()、setCode()、setDelay()、json() 以及 headers 和 code 属性完成输出控制。

下面是一个根据提交商品明细自动计算订单总额，并回显调用方货币 header 的脚本示例：

const body = $$.mockRequest.body;const items = body.items || [];const subtotal = items.reduce((sum, item) => {return sum + item.price * item.quantity;}, 0);const currency = $$.mockRequest.headers["x-currency"] || "USD";$$.mockResponse.setCode(201);$$.mockResponse.setBody({orderId: Math.floor(Math.random() * 90000) + 10000,currency: currency,subtotal: subtotal,tax: Number((subtotal * 0.08).toFixed(2)),total: Number((subtotal * 1.08).toFixed(2))});

它的执行流程是这样的：智能 Mock 先生成初始响应，然后脚本读取 $$.mockRequest 和当前的 $$.mockResponse，执行你的自定义逻辑，再通过 $$.mockResponse.setBody()（以及需要时的 setCode、setDelay 或 headers）覆盖最终输出，最后引擎返回结果。如果你还想继续扩展数组处理或日期计算逻辑，MDN Ja vaScript 参考文档会很有帮助。

一个容易让人绊倒的规则

Mock 脚本只对 Smart mock 生效，不适用于 mock 期望，也不适用于响应示例。这一点非常关键：你不能把 mock 脚本和基于期望的响应同时叠加使用。如果某条期望命中了请求，那么脚本就不会执行。因此，请为每个接口明确选择一种方案：如果你要根据固定规则分支并返回预设 body，就使用 mock 期望；如果你要在 Smart mock 生成的数据基础上继续计算和加工，就使用 mock 脚本。

优先级顺序的解析机制

综合起来，Apifox 在处理任意一个 mock 请求时，大致遵循以下执行顺序：

首先，它会从上到下检查你配置的 mock 期望。第一条所有条件都匹配的期望会立即生效并返回响应。这也是为什么自定义规则优先于 Smart mock：一旦命中某个期望，后续内容就会被中断，下面的规则和智能 Mock 都不会再执行。
如果没有任何期望命中，Apifox 就会回退到你在“项目设置 - 功能设置 - Mock 设置”中定义的 Mock 方式优先级。在这个层级下，Smart mock（以及绑定在它上面的 mock 脚本）才会生成最终响应。

你可以这样理解：先匹配特定规则，再使用自动生成数据。将 mock 期望按照“从最具体到最宽泛”的顺序排列；如果你希望始终有兜底返回，可以在最下方保留一个无条件规则，或者把未命中的场景交给 Smart mock 处理。若想进一步判断不同业务该使用哪一层能力，可以参考 API mock 使用场景指南，它对常见场景和功能做了清晰对应。

发布前需要注意的易错点

在正式使用前，提前了解以下限制，可以帮你避开很多令人困惑的调试问题：

Parameter 条件不支持 {{variables}}。Apifox 的项目变量和环境变量不能直接用于 mock 期望，因此条件中必须写字面量值。
Body-parameter 条件目前只支持 JSON，不支持 XML，而且需要通过名称字段中的 JSON path 进行匹配。
条件中的请求 body 格式必须与接口定义保持一致。比如 form-data 接口，就必须使用 form-data 方式进行 Mock，不能改成 JSON。
在 mock 脚本内部，没有日志函数，pm 对象也不可用（因为它与测试脚本的执行环境不同），同时也无法直接使用 Apifox 变量。所以建议保持脚本逻辑自包含、可独立运行。

官方文档并没有说明这些功能受套餐版本限制。本地 Mock 与云端 Mock 的核心差异主要在开关层面：正如前面提到的，每个环境都可以独立启停规则，而不是被付费门槛阻挡。

使用 Apifox CLI 实现工作流自动化

Apifox 的 Mock 能力本身主要由 GUI 和云端提供。mock 引擎通过本地 Mock URL 与云端 Mock URL 对外提供服务，目前并没有一个 CLI 命令可以直接启动正在运行的 Mock 服务端。Apifox CLI 真正带来的价值，是帮助你管理和更新构成这些 Mock 的项目资源。

从本质上说，Mock 响应是基于接口数据模型生成的，因此 Mock 准不准确，最终取决于接口规范本身是否足够准确。CLI 以及其背后的 AI 编码助手（Cursor、Claude Code、Trae、Codex）都可以直接在项目中创建或更新接口与数据模型。只要你在代码里把 API 契约维护正确并同步到项目，Mock 输出就能持续保持一致，整个流程不需要开发者反复手动打开应用处理。

而当 Mock 已经帮助前端解除开发阻塞后，同一个项目中的测试场景还可以在 CI 环境中以无头（headless）模式运行，从而依据 Mock 所描述的接口契约去验证真实后端：

apifox run -t -e -r cli

这一条命令就能执行你的测试场景并输出结果，让 Mock 与验证共享同一个单一事实源。想了解安装和接入方式，可以参考 Apifox CLI 安装指南，以及 GitHub Actions 中的 Apifox CLI 实战演练。

FAQ

为什么即使条件看起来写对了，我的 mock 期望还是没有生效？绝大多数情况下，原因要么是顺序错误，要么是请求格式不匹配。Mock 期望按自上而下顺序评估，并以第一个匹配项为准，所以如果一条宽泛的无条件规则排在前面，它会直接吞掉你的请求。另外，也要确认 body 格式与接口规范一致，比如 JSON body 要对应 JSON path，表单接口则要使用 form-data 布局。如果你想重新核对基础配置，可以回看 API mock 概览。

我可以在同一个响应中同时使用 mock 脚本和 mock 期望吗？不可以。Mock 脚本只在智能 Mock（Smart mock）模式下运行，而 mock 期望和响应示例不会触发脚本。一旦某条 mock 期望匹配成功，脚本就不会再执行。因此，每个接口都应明确选择一种方式：规则分支用 mock 期望，动态计算输出用 mock 脚本。

如何在不影响默认 200 响应的前提下返回 401 或 500？最简单的方法是新增一个专属 mock 期望，并设置一个由客户端可控的触发条件（通常 header 最好用），然后在“更多”标签页中配置 HTTP 状态码（HTTP Status Code）。这样默认响应仍然保持 200，只有在条件匹配时才返回对应错误码。

条件里可以使用我的环境变量吗？不可以。Apifox 的 {{variable}} 变量值无法在 mock 期望中使用，而且 parameter 条件也不支持 {{variables}}。因此条件中必须写明确的字面量。

如果当前没有任何 mock 期望匹配，请求会怎么处理？这时，Apifox 会回退到“项目设置 - 功能设置 - Mock 设置”中的“Mock 方式优先级”；在这种情况下，智能 Mock 会根据你的数据模型自动生成响应。不过从稳定性角度看，如果你需要可预测的兜底行为，通常更推荐添加一个空白条件的兜底 mock 期望。

总结

Smart mock 适合处理通用场景，而 mock 期望则专门解决所有带有 if 判断的分支场景：比如已知用户返回 200，否则返回 401；根据订单状态返回不同 body；或者按需模拟 500 错误。只有当你需要规则无法表达的动态计算输出时，才应该使用 mock 脚本，并且要记住它只对 Smart mock 生效。只要掌握优先级顺序——特定期望优先，智能生成次之——你的 Mock API 就能像真实后端一样完成分支处理。现在就下载 Apifox，创建你的第一个条件 Mock，免费且无需信用卡。