请求匹配与响应
请求匹配
在「匹配条件」里加一行即可要求请求必须满足某个条件,多个条件全部满足才算命中:
| 来源 | 操作符 | 说明 |
|---|---|---|
| 请求参数 / 请求头 | 等于 EQ | 值完全相等(期望值留空时退化为"该参数存在即可") |
| 请求参数 / 请求头 | 不等于 NE、包含 CONTAINS、正则 REGEX | 常规比较 |
| 请求参数 / 请求头 | 存在 EXISTS、不存在 MISSING | 只看有没有 |
| 请求参数 / 请求头 | 大于 GT、小于 LT | 数值或字典序比较 |
请求体是 JSON 时,一级字段也会并入参数池,可以直接拿 type、userId 之类的字段做条件。
响应能力
基础
一份响应 = 状态码 + Content-Type + 响应内容 + 响应头 四件套;默认响应有一份,每个条件响应也各有一份,互相独立。
- 状态码:下拉里挑常用的,也可以直接填任意值(比如 418);
- Content-Type:同样可下拉可选、可手填,留空默认 JSON;
- 响应头:一行一个
KEY: VALUE,值里也能用模板变量,例如X-Request-Id: {{faker.string.uuid}}(#开头的行是注释,会被忽略); - 响应内容:支持模板变量,旁边有「格式化 / 紧凑」和「清除」两个按钮;
- 延迟:模拟慢接口,可配区间做抖动;调用时用
?delay=800可临时覆盖。
编辑框:行号、折叠与一键排版
响应内容、故障响应体、数据集的数据行这几个输入框都是带行号的代码编辑器(用的是开源的 CodeMirror,随程序一起本地加载,不依赖外网):语法着色、括号匹配、代码块折叠都有,长 JSON 一眼能看清结构。
- 格式化 / 紧凑:跟「文本 / 数据集」同一款的分段控件,就在「清除」左边、整组靠右;高亮的那一项表示内容当前的状态,点另一项即可在「缩进排版」和「压缩成一行」之间切换;
- 编辑框只能上下拖高(右下角拖拽),宽度固定跟着布局走,拖大之后不再受默认高度限制;
- 高度跟着内容长,长 JSON 不会被截断;内容只有一两行时也不会缩成一条,响应内容、故障响应体都有一个高度下限(首页那个「响应内容」输入框同样),想更矮的话往下拖即可,拖过之后这个下限就不再生效;
- 排版时保留
{{...}}模板变量:原来写在引号里的还是字符串,原来裸写的({"n":{{faker.number.int}}})也仍然裸写,不会被顺手加上引号变成字符串; - 内容本身不是合法 JSON / JSON5 时会给出提示,不会改动你写的东西;
- 内容特别大时自动退回普通输入框,避免编辑卡顿。
JSON5:响应内容可以这样写
响应内容不要求是严格 JSON:按 JSON5 写也能用,服务端返回前会自动转成标准 JSON,调用方拿到的永远是合法 JSON。
{
// 行注释、块注释都能写
name: '张三', // 键可以不加引号,字符串可以用单引号
tags: ['a', 'b',], // 尾随逗号随便加
price: .5, // .5、1e3、0xFF 都认
mask: 0xFF,
desc: '这一行还没完\
继续写',
}
调用方实际收到的是:
{"name":"张三","tags":["a","b"],"price":0.5,"mask":255,"desc":"这一行还没完继续写"}
响应内容的长度上限
单个"响应内容"默认最多 10 万字符(约 100 KB),超了保存会被拒绝,并提示实际超了多少。默认响应、多响应序列、条件响应、故障响应分别计算。
需要返回大段内容时,别整段写死:用循环 {{#repeat}} 按条数生成,或挂一个数据集动态取。上限可用 --max-body-size 调整。
- 只有 Content-Type 里含 json 才做转换;纯文本 / HTML / XML 一律原样返回;
- 已经是标准 JSON 的内容保持原样(连你的缩进排版都不动),不会被重新格式化;
- 真解析不出来(比如括号没闭合)也不报错,按原文返回,方便你边写边调;
- 编辑框下方有实时提示:会标明是「标准 JSON」还是「JSON5」,也能一键转成标准 JSON;
- 管理 API 的请求体同样支持 JSON5,带注释的 JSON 提交上去也能正常创建 / 更新规则。
请求匹配条件
在响应内容上方的「请求匹配条件」里加行即可要求请求必须满足某条件,多个条件全部满足才算命中;留空表示任何请求都命中。
故障注入(默认折叠)
底部折叠区现在只放故障相关的两项,用来压测客户端的容错能力:
- 延迟:可填下限 / 上限,上限大于下限时在区间内随机;调用时也能用
?delay=800临时覆盖; - 故障率:填 0-100 的百分比,按概率返回故障响应(默认 503,状态码与响应体都可自定义)。
跨域与鉴权
这两项不在折叠区里,就在「可见性 / 有效期 / 状态」的下一行:
- CORS:默认跟随服务配置,也可以对单条规则单独开关;
- Bearer 鉴权:勾选后不带
Authorization: Bearer xxx返回 401(私有路径不强制,按需开启);列表里会带一个「鉴权」标记。
列表里的颜色
- 可见性:私有用绿色,公开用黄色,公开会被所有人看到,所以给个更醒目的颜色;
- 有效期:3 天内到期(含已过期)显示红色,30 天以上或永久有效显示绿色,中间档是灰色。
条件响应
同一个地址,按请求内容返回不同的响应。控制台「响应内容」区域有三个页签:默认响应、条件响应与响应序列;先在条件响应页签里添加条目,每条配一组条件 + 一份独立响应,而每份响应的内容又可以在文本与数据集之间二选一(状态码 / Content-Type / 响应头两种来源下都一样填)。请求进来时从上往下匹配,第一个满足的生效,都不满足才用默认响应。
条件1: 参数 vip 等于 1 → {"level":"vip","discount":0.7}
条件2: 参数 vip 等于 0 → {"level":"normal","discount":1}
都不满足 → 默认响应 {"level":"guest"}
典型用法:
- 按
id分流:id=1返回成功、id=2返回空、其它返回 404; - 按请求头分流:带
X-Debug: true时返回一个延迟 5 秒的响应,用来复现超时; - 按请求体分流:JSON 里
type=vip与普通用户返回不同字段。
判定顺序即配置顺序,所以更严格的条件要放前面;条件留空的条目视为恒真,适合放最后当兜底。条件来源和操作符与「请求匹配」完全一致(参数 / 请求头 × 等于 / 包含 / 正则 / 存在 / 大于…)。
响应序列(同一个地址,多次调用给不同结果)
条件响应是「看请求给不同结果」,响应序列是「不看请求,按固定规则轮着给」。同一个页签区里的第三个页签,添加若干条响应(每条与默认响应结构完全一致:状态码 / Content-Type / 响应内容 / 响应头),再选一种推进方式:
| 推进方式 | 行为 | 适合场景 |
|---|---|---|
| 循环(CYCLE) | 1 → 2 → … → 最后一条 → 回到第 1 条,周而复始 | 重试:第一次 500、第二次 200;轮询任务状态 |
| 随机(RANDOM) | 每次调用随机挑一条(等概率) | 灰度:一部分用户看到新字段,一部分看到旧的 |
| 加权随机(WEIGHTED) | 按每条的权重占比随机:权重 9 与 1 的两条,大约 90% / 10% 出现 | 不稳定的线上接口:大部分成功、偶尔失败 |
| 按次切换(SWITCH) | 前「每几次切换」条请求返回第 1 条,之后切到第 2 条……走到最后一条后停住 | 重试两次才成功:switchAfter=2 时第 1、2 次失败,第 3 次起成功 |
| 单次(ONCE) | 1 → 2 → … → 最后一条后固定返回最后一条,不再回头 | 状态机:创建中 → 成功,之后一直是成功 |
第 1 条 {"status":"pending"} 状态码 200
第 2 条 {"status":"success","file":"a.png"} 状态码 200
推进方式 = 循环 → 第 1、3、5… 次调用拿到 pending,第 2、4、6… 次拿到 success
推进方式 = 按次切换(每 2 次)→ 第 1、2 次 pending,第 3 次起一直 success
- 序列为空时,一切照旧走默认响应;一旦填了内容,默认响应就只在序列取不到时兜底;
- 条件响应的优先级仍在序列之前:命中某个条件响应就直接返回它,不走序列;
- 每条响应的延迟、故障注入等仍是规则级共享的,不按条目区分。
调试头:想看第几条就看第几条
连着调 3 次才能看到第 3 条响应太麻烦,而且会打乱别人正在用的轮换顺序。给请求加这几个头即可(只影响这一次调用):
| 请求头 | 作用 |
|---|---|
X-Mock-Index: 2 | 直接返回序列里的第 3 条(从 0 开始数),不推进游标,别人连着调用的顺序不受影响;下标越界时取最后一条 |
X-Mock-Error: 1 | 强制走故障响应,不用把故障率临时改成 100(1 / true / yes / on 都算真) |
X-Mock-Delay: 800 | 临时延迟 800 毫秒再返回,优先级高于 ?delay= 与规则上的配置 |
curl -H 'X-Mock-Index: 2' http://127.0.0.1:8080/m/abc
响应头里也会回一个 X-Mock-Index,告诉你这次实际用的是序列里的第几条(非序列响应不回这个头)。「代码」弹窗里的「序列·指定第 N 条」示例就是带这个头的。