模板变量与假数据
模板变量
响应体、响应头、Content-Type 里都能写模板变量,每次请求实时计算。下面按类别列了全部变量,点一下即复制。
写的时候有两处帮忙:编辑器里输入 {{ 会弹提示(见代码提示),页面右侧还有一个速查抽屉随时可翻(见右侧的速查抽屉)。下面这份是完整清单,点一下即复制。
写法约定
- 统一使用双花括号
{{...}};旧的${...}写法已废弃,会原样输出; - 请求相关的变量一律带
request.前缀:{{request.query.id}}、{{request.header.x-token}}、{{request.body.user.name}}; - 支持括号参数,如
{{faker.number.int(1,99)}}、{{faker.number.int(1000,9999)}}、{{image(32,32)}}; - 取不到值、或变量未识别时原样保留,不会把响应体弄坏;想兜底就用竖线给默认值:
{{request.query.page|1}}; - 未登录(首页简化版)创建的接口不做模板解析,响应里的
{{...}}会原样返回;需要动态内容请登录后到控制台创建。
默认值:竖线
取值类变量在取不到值时会用竖线后面的内容兜底,避免响应里出现 "page":"" 这种把前端搞崩的空值。
{{request.query.page|1}} // 没传 page 就返回 1
{{request.header.x-token|匿名}} // 没传这个请求头就返回「匿名」
{{{request.query.q|匿名}}} // 三括号同样支持默认值
{{default(request.query.page,1)}} // 等价写法:返回第一个非空参数
- 只有取不到值时才走默认值;变量本身写得不对(引擎不认识)仍然原样保留,方便你发现拼写错误;
- 默认值里也能写
{{...}},例如{{request.query.uid|{{faker.string.uuid}}}}。
三括号:JSON 安全输出
假数据里可能带引号、换行,直接塞进 "..." 会把整段 JSON 写坏。用三个花括号 {{{...}}} 时,引擎会先把结果按 JSON 规则转义("、\、换行等)再输出,结构一定合法。
{
"name": "{{{faker.person.fullName}}}",
"desc": "{{{faker.lorem.paragraph}}}"
}
- 双括号
{{...}}是原样输出(历史行为,不变);三括号{{{...}}}才转义; - 三括号只做转义,不会自动加外层引号,
"{{{x}}}"的引号要自己写; - 只在响应体里有意义,响应头里不需要(响应头本身不能含换行)。
函数助手
除了取值,还内置了一批常用的小函数,写法与 faker 一致:{{名字(参数,参数)}}。参数里可以再嵌套 {{...}},会先渲染内层。
{{oneOf(男,女)}} // 随机选一个
{{concat(NO-,{{now.date}},-,001)}} // NO-2026-09-18-001
{{padStart({{request.seq}},6,0)}} // 000001
{{upper(abc)}} {{lower(ABC)}} // ABC abc
{{len(abcdef)}} {{substr(hello,0,4)}} // 6 hell
{{replace(a-b-c,-,)}} // abc
{{base64(hello)}} {{md5(abc)}} // 编码 / 摘要
{{urlenc(a b)}} {{urldec(a%20b)}} // URL 编解码
- 参数按逗号切分;参数本身含逗号时用引号包起来:
{{oneOf('a,b',c)}}; - 嵌套层数上限 4 层,超了就原样保留,不会因为写错把服务拖死;
{{default(a,b)}}返回第一个非空参数,和竖线默认值等价,适合嵌套在函数里用。
{
"id": "{{faker.number.int(1,9999)}}",
"keyword": "{{request.query.keyword}}",
"traceId": "{{request.header.X-Trace-Id}}",
"orderNo": "{{request.path.orderNo}}",
"createdAt": "{{now.iso8601}}"
}
速查
| 变量 | 含义 |
|---|---|
{{request.query.名}} | query 参数 / 表单字段({{request.param.名}} 同义) |
{{request.header.名}} | 请求头,名称大小写不敏感 |
{{request.cookie.名}} | Cookie,如 {{request.cookie.sessionId}};先按名称精确匹配,取不到再忽略大小写重试;没有该 Cookie 时没有值,需要兜底请写 {{request.cookie.名|默认值}} |
{{request.cookie}} | 原始 Cookie 头全文(a=1; b=2) |
{{request.body}} | 原始请求体全文 |
{{request.body.a.b}} | JSON 请求体按路径取值,数组用下标 items.0.name |
{{request.path.名}} | 路径变量,需把路径写成 order/{orderNo} |
{{request.method}} {{request.path}} {{request.ip}} | 方法 / 相对路径 / 调用方 IP |
{{request.seq}} | 本规则第几次被调用(从 1 开始),配合多条响应可做「前 3 次成功、第 4 次失败」 |
{{变量|默认值}} | 取不到值时的兜底,见默认值 |
{{{变量}}} | 三括号:结果按 JSON 转义后输出,见JSON 安全输出 |
{{#repeat N}} … {{/repeat}} | 循环生成数组,配合 {{index}} / {{index1}},见循环(速查表里归在「语法」页签) |
{{函数(参数)}} | 内置小函数:oneOf concat len substr replace upper lower trim padStart padEnd base64 md5 sha256 urlenc default,见函数助手;随机数字请直接用 {{faker.number.int(1,99)}} |
{{faker.模块.方法}} | 假数据,命名与 fakerjs 完全一致,共 28 个模块 / 260+ 个方法(详见下文) |
{{now.*}} | 时间:iso8601 / unix / unix_ms / date / time / datetime / rfc1123 |
{{now(格式)}} | 自定义时间格式,如 {{now(yyyy-MM-dd)}}、{{now(yyyy年MM月dd日 HH:mm)}} |
{{image}} {{image(32,32)}} | 占位图片,返回内联 SVG 的 data URI,不依赖外网;{{image(宽,高,背景色)}} 可定制 |
{{$randomInt}} {{$guid}} … | Postman 动态变量,官方 118 个都能直接用(详见下文):从 Postman 集合导入的示例响应不用改,手写也认 |
假数据:完全对齐 fakerjs
假数据部分按 fakerjs 实现,模块名、方法名、参数都照搬,所以你在 fakerjs 文档里看到的写法,搬到这里的 {{faker.xxx}} 里基本都能直接用,不需要查第二套命名。
{{faker.person.fullName}} // 张伟 / John Doe
{{faker.internet.email}} // 邮箱
{{faker.phone.number}} // 手机号
{{faker.location.city}} // 城市
{{faker.company.name}} // 公司名
{{faker.commerce.productName}} // 商品名
{{faker.string.uuid}} // UUID
{{faker.number.int(1,99)}} // 区间整数
{{faker.datatype.boolean}} // true / false
{{faker.date.past()}} // 过去的时间
{{faker.lorem.paragraph}} // 一段随机文字
- 命名一律是
{{faker.模块.方法}},比如faker.person.firstName、faker.location.zipCode、faker.vehicle.model; - 参数支持位置参数和 fakerjs 的命名参数两种写法,等价:
{{faker.number.int(1,99)}}与{{faker.number.int({min:1,max:99})}}; - 28 个模块全部可用:person、location、internet、company、commerce、lorem、word、color、animal、vehicle、music、book、airline、database、science、system、hacker、git、finance、food、medical、phone、image、string、number、datatype、date、helpers;
- 完整方法清单见 fakerjs API 文档;控制台编辑器的「模板变量」面板里也按模块分好组,点击即复制;
- 早期版本里的
{{faker.name}}、{{faker.uuid}}、{{uuid}}、{{random(1,99)}}这类写法已全部移除:随机数用{{faker.number.int(1,99)}},唯一 ID 用{{faker.string.uuid}}。
循环:生成数组
用 {{#repeat 次数}} … {{/repeat}} 把一段内容重复若干次,元素之间会自动补逗号,所以直接写 JSON 对象就能得到合法数组。
{
"total": 3,
"data": [
{{#repeat 3}}
{"id": "{{faker.string.uuid}}", "seq": "{{index1}}"}
{{/repeat}}
]
}
- 次数可以是数字,也可以是任意模板变量,由请求决定:
{{#repeat request.query.count}}…{{/repeat}},调用?count=10就返回 10 条; - 循环体内可用
{{index}}(从 0 开始)与{{index1}}(从 1 开始)当序号; - 块里写不写尾随逗号都行,引擎会去掉最后一项多余的逗号;
- 次数最大 1000,非数字按 0 处理(得到空数组),不会把服务打爆。
图片
{{image}} 会生成一张灰色占位图,直接以 data:image/svg+xml;base64,... 的形式内联在响应里,不需要外网就能显示,放在 <img src>、JSON 的头像字段里都能用。
{
"avatar": "{{image(32,32)}}",
"banner": "{{image(640,320,#2563eb)}}",
"square": "{{image(120)}}"
}
{{image}}:默认 200×200;{{image(32,32)}}:指定宽高(也支持{{image(32x32)}});{{image(64,64,#2563eb)}}:第三个参数是背景色,第四个可再指定文字颜色;- 想要真实照片可改用外链:
{{faker.image.url(300,300)}}(随机图)、{{faker.image.avatar}}(头像)。
Mock.js 语法(从 Mock.js / YApi / EasyMock 迁过来直接贴)
除了 {{...}},响应体还支持 Mock.js 那套数据模板:值里写 @占位符,键名里用竖线写生成规则。从 Mock.js、YApi、EasyMock 复制出来的模板可以直接粘进响应内容,不用改写。
{
"list|3": [{
"id|+1": 1,
"name": "@cname",
"city": "@city",
"age|18-60": 0,
"vip|1": true
}]
}
| 写法 | 位置 | 效果 |
|---|---|---|
@cname @city @email @uuid @phone @company | 值 | 占位符:换成对应的随机数据 |
@integer(1,100) @float(1,10,2) @pick(男,女) @date(yyyy-MM-dd) @cword(3) @image(200x200) | 值 | 带参数的占位符,参数写法与 Mock.js 一致 |
list|10 | 键名 | 数组重复 10 次,每份内容重新生成(里面的 @cname 各不相同) |
id|+1 | 键名 | 自增:1、2、3…… 配合 list|N 得到连续 id |
age|18-60 | 键名 | 区间随机整数 |
score|1-100.1-2 | 键名 | 随机小数:整数位 1~100、小数位 1~2 位 |
vip|1 / vip|1-9 | 键名 | 布尔按概率为真(1/2、1/10) |
tag|1 | 键名 | 数组随机取 1 个;|2 及以上是取 2 个 |
user|2 | 键名 | 对象随机取 2 个字段 |
name|3 | 键名 | 字符串重复 3 次 |
规则上「Mock.js 语法」这个开关默认开着;想让响应所见即所得(写了什么就返回什么)时关掉它。生成过程出错会回退原文,接口不会变成 500。
占位符:覆盖与细节
官方 Mock.js 的占位符全都支持(Basic / Image / Color / Text / Name / Web / Address / Helper / Miscellaneous,连 @bool @int @char 这些别名也算),另外补了几个迁移时常见的:@timestamp(毫秒,@timestamp(s) 要秒)、@decimal、@money、@tel / @mobile。
- 文本类的参数是长度:
@word(10)出 10 个词、@ctitle(5)是 5 个中文词、@csentence(30)约 30 字、@paragraph(3)是 3 句、@text(2)是 2 段;写成区间@cword(2,8)就在区间里取。 - 中英文按占位符名分:
@word@sentence@title@text出英文,@cword@ctitle@csentence@ctext出中文词(是词,不是随机字)。 @now第一个参数可以是时间单位:@now(day)= 今天 00:00:00、@now(year)= 今年 1 月 1 日;要格式就写@now(yyyy-MM-dd),两个都给是@now(day, yyyy年MM月dd日)。- 地址是一级一级往下取的:
@address不会出现「广东省苏州」这种错配;@city(true)/@county(true)带上级前缀。 @image/@dataImage返回内联 SVG 占位图(站内没有图片服务,这样任意字段都能直接显示)。- 不认识的占位符原样保留:
user@example.com这类字符串不会被改坏。
JSONP 兼容
老项目用 <script src> 跨域时还会带上回调名,这时接口会把响应包成脚本:
GET /m/xxx?callback=cbFn
cbFn({"code":0,"data":{...}});
- 认这几个参数名:
callbackjsonpcbjsoncallback; - 响应
Content-Type自动换成application/javascript,浏览器才会当脚本执行; - 回调名必须是合法 JS 标识符:
?callback=alert(1)//这类按"没传"处理,回普通 JSON——既不留 XSS 口子,也不报错; - 不带回调参数时接口照旧返回 JSON,正常调用不受影响。规则上「JSONP 兼容」开关可以关掉。
编辑器里的代码提示
输入 {{ 会弹出模板变量清单,输入 @ 会弹出 Mock.js 占位符,Ctrl+空格 可随时手动唤起。上下键选、回车插入,插进去之后光标会自动选中需要你填的部分(比如 {{request.query.名称}} 里的「名称」)。清单来自服务端,faker 与 Mock.js 的名字都直接取自实现,不会出现"提示里有、用了没反应"。
凡是支持模板变量的输入框都有提示,不只是响应内容:响应头的值、状态写入的值、故障响应头、Content-Type、数据集的数据行,敲 {{ 一样会弹。
路径里的变量会实时进提示:路径写成 user/{name1}/list,提示里第一条就是 {{request.path.name1}};改路径、加变量,下一次弹提示立刻跟着变。
右侧的速查抽屉
模板变量速查表做成右侧抽屉:竖着的「模板变量」把手贴在页面右边缘、垂直居中,点一下面板就从最右侧向左滑出,高度与页面齐平;页面滚到哪儿它都还在,不用滚回去翻。面板够宽,变量与说明一行一条铺开,右侧还有搜索框,知道要什么(比如 uuid、中文姓名)时直接搜,比翻分组快。
- 左侧竖排的是分组,点一下切换;接口路径里写了变量,会多出「本接口路径」这一组,直接列出
{{request.path.xxx}}; - 点某个变量 = 复制(复制出来愿意粘哪儿粘哪儿,不会往你正在编辑的框里插);
- 搜索是跨分组的,命中会标出它属于哪一组;切分组即退出搜索,按
Esc先清搜索再关抽屉; - 抽屉展开时那条竖把手会自动藏起来(面板已经满高铺到最右,两个控件叠着反而像在打架),收起后又回到右边缘。
- 点抽屉外面收起,也可以点右上角的 ×。
代理转发:绕开浏览器的跨域(需后台审核)
本地页面里直接 fetch 别家的接口,会被浏览器同源策略拦掉,因为目标站点(知乎、微博、百度这类)不会给任何来源回 Access-Control-Allow-Origin。让请求先打到 anymock、由服务端去取,浏览器眼里这就是在请求自己的域名,跨域限制自然不成立。
用法:在新建 / 编辑 API 的「代理转发(需后台审核)」里填目标地址。命中后这条 API 不再返回你配的内容,而是把对方的状态码、响应头、正文原样带回来,响应头里会多两条:X-Mock-Proxy-Status(审核状态)、X-Mock-Proxy-Cost(访问目标花了多少毫秒)。
// 浏览器里直连:被同源策略拦下
fetch('https://top.baidu.com/api/board?tab=realtime') // ✗ blocked by CORS
// 改成打自己的 mock 地址,由服务端代取
const d = await fetch('/m/scene/proxy-hot').then(r => r.json());
但这条能力也等于「让这台服务器替你访问任意 URL」,所以收紧了几处:填了地址就要后台审核;审核通过前调用返回 403 与一句说明,不会真的发请求出去;被驳回时响应体里带着原因。
- 改地址会重新进审核队列:老地址审过不代表新地址安全——这是整套机制唯一要盯住的口子;只改名字、改响应不会重置审核;
- 只认
http/https,地址里不能带用户名密码(会进日志和备份); - 默认拒绝解析到内网的目标(回环 / 私有网段 / 链路本地),也不跟随重定向;本机联调内网服务时可在配置里开
proxy.allow-internal,公网部署务必保持关闭; - 不转发 Cookie 与 Authorization,上游回的
Set-Cookie也会摘掉:代理公开接口用不上,带上反而等于把调用者的凭据交给第三方; - 单次转发有超时(默认 15 秒)与响应体积上限(默认 4MB),超时回
504、其它失败回502,都会在响应体写明原因; - 查询串会带到上游,所以
?limit=20这类过滤照常生效;匿名创建的接口不给配代理(查不到归属人的不能放行)。
管理员一侧在后台「代理审核」页签:待审的排在前面,点通过放行、点驳回必须写原因(这句会直接显示给创建者)。它与「内容审核」是两件事——驳回代理不停用规则本身,只掐掉往外发请求。