Anymock

数据集

数据集(像真库一样)

把某条响应绑定到数据集,它返回的就不再是写死的文本,而是一个自带数据的 REST 资源。

入口在新建 / 编辑 API 的「响应内容」里,而且是逐条响应选的:先选上面三个页签之一(默认响应 / 条件响应 / 响应序列),再在这条响应的「响应内容」标题右侧用两个小按钮选来源——

  • 文本(默认):出现文本框,自己写响应体,支持模板变量与 JSON5;
  • 数据集:文本框收起,改为从已有数据集里挑一个,可再填过滤字段;这条响应的内容就由数据集生成(固定返回 JSON,支持分页 / 搜索 / 排序 / 增删改),不再用手写响应体。

因为是挂在响应上的,所以默认响应、每个条件响应、序列里的每一条都能各自选:比如「第 1 条返回 500 文本、第 2 条返回数据集」这种混合也配得出来。状态码、Content-Type、响应头、延迟在两种来源下都一样可用。

保存以当前选中的那一类为准:选「文本」时忽略数据集下拉的选择,选「数据集」时忽略文本框里写的内容。所以来回切换不会留下"看不见但仍在生效"的配置;切回文本时文本框里原来的内容也还在,不会被清掉。

自建数据集

登录后到控制台「数据集」页,点右上角创建数据集,填一句名称(就是说明,中英文都行,比如「商品列表」)和一段 JSON 数组即可,编号由系统自动分配。表单里还有「从模板创建」,选一份系统模板数据集会把它的原始数据行(也就是配方,模板变量还在)带进来, 保存那一刻才渲染成真实数据,落一份属于你自己的副本,所以行数、字段、生成规则都能先改,改它也不会动到模板。

  • 名称只是给人看的,重名不冲突;真正用来关联的是编号(形如 ds_7f3a2c1d);
  • 在新建 API 的响应内容里切到「数据集」,从下拉选中它,这条响应就与编号绑定;下拉里只有你自己创建的数据集;
  • 编号是随机分配的,别人猜不到,也绑不了你的数据集:每个用户只能操作自己创建的数据集;
  • 数据集列表顶部有来源过滤下拉:我的数据集 / 全部可见(我的 + 模板)/ 系统模板数据集。默认看「我的数据集」,切换只是前端过滤,不会重新请求。
  • 列表里可以「查看数据」「编辑」「删除」;点编辑会把原数据带进下面的表单,改完保存即可。删除后绑定它的接口会取不到数据。

系统模板数据集

站点维护者准备了几份通用数据(商品、用户、待办、文章、评论、名言、购物车),它们就是系统模板数据集。模板数据集是共享的,普通用户不能直接改;想基于它做自己的数据,用「从模板创建」复制一份即可,复制出来的就是你的私有数据集;带过去的是数据行原文而不是已经生成好的死数据。

数据行支持模板变量

数据行里可以直接写模板变量,保存时渲染一次并落盘。也就是说数据是「生成好的」,不是每次调用再随机,翻页、排序、改单条都不会变。常用写法:

[
  { "id": "{{index1}}", "name": "{{faker.person.fullName}}", "email": "{{faker.internet.email}}" },
  { "id": "{{index1}}", "price": {{faker.commerce.price}}, "onSale": {{faker.datatype.boolean}} }
]
  • {{#repeat 20}}:把后面一段内容重复 20 次(放在最外层数组里,重复的是数组元素,不是整个数组);
  • {{index}} / {{index1}}:重复序号,从 0 / 从 1 开始,正好用来当 id;
  • {{faker.xxx}}:任意假数据函数,见前面「模板变量」一节;
  • 其余 {{faker.string.uuid}}、{{now.iso8601}}、{{faker.number.int(1,100)}} 等通用变量同样可用。
{{#repeat 20}}
{ "id": {{index1}}, "title": "{{faker.commerce.productName}}", "price": {{faker.commerce.price}} }
{{/repeat}}

展开后就是 20 条带序号的商品。注意 repeat 里的元素不要写外层中括号、也不要在元素之间加逗号,引擎会自动拼成数组。渲染后如果不是合法 JSON,保存会直接报错并提示原因,不会写入脏数据。

不想手写模板变量:用可视化生成

数据行上面有个「可视化生成(不用自己写模板变量)」,展开后是一张字段表:左边填字段名,右边选它是什么(姓名、手机号、价格、时间、随机整数……一共几十种),再填生成几行,点一下就把整段模板填进下面的「数据行」。

  • 上面还有一键预设:用户 / 商品 / 订单 / 文章,点一下直接铺好一组字段,改改就能用;
  • 生成的仍然是模板,点保存时才渲染成真实数据落盘,所以生成完还能照着自己的需要改;
  • 字符串字段用的是三括号 {{{...}}}:值里的引号、换行会被转义,长文本(比如 faker.lorem.paragraph)也不会把 JSON 写坏;
  • 数字 / 布尔不加引号,价格、金额、随机整数这些拿去做排序比较才对;
  • 最多 1000 行;替换前如果「数据行」里已经有内容,会先问一句。

「查看数据」会用只读编辑器展示:默认就是缩进排好的样子,右上角可以切「紧凑」压成一行,不用再去翻一行行的原始 JSON。

怎么用:查询 / 过滤 / 搜索 / 分页

绑定数据集后,这个地址就不再返回你写死的文本,而是像查一张真表。列表响应统一长这样:

{
  "data": [ { "id": 1, "title": "iPhone 9", "price": 549 }, ... ],
  "total": 100,     // 过滤后一共多少条(不是本页多少条)
  "page": 1,        // 当前第几页(从 1 开始)
  "pageSize": 10,   // 每页几条
  "totalPages": 10, // 一共几页
  "hasMore": true,  // 还有没有下一页
  "skip": 0,        // 老字段,等价于 (page-1)*pageSize
  "limit": 10       // 老字段,等价于 pageSize
}
参数示例说明
page / pageSize?page=2&pageSize=10分页就写这两个:第几页、每页几条。跳过几条由后台算,前端不用自己写 (page-1)*size。size / perPage 是 pageSize 的别名,只给 page 时每页默认 10 条;pageSize=0 表示一次给全。都不给时默认每页 30 条
limit / skip?limit=10&skip=20老写法(等价于 pageSize / page),继续支持:默认 limit=30;limit=0 或负数表示返回全部(此时不截断,skip 仍生效)
q?q=phone全文搜索:在所有字符串字段里模糊匹配(含嵌套对象与数组),忽略大小写
sortBy / order?sortBy=price&order=desc排序。order 只有 desc 是降序,其它都按升序;能转成数字的按数字比,否则按字符串比。可以排多个字段:?sortBy=category,price&order=asc,desc(order 按位置一一对应,写少了按升序)
比较算子?price_gte=100字段名后面接算子就不按等值比,可用的有:_gte(≥)、_lte(≤)、_gt(>)、_lt(<)、_ne(≠)、_like(模糊,* 与 % 是通配符)、_in(逗号分隔,命中任一)、_nin(都不命中)、_regex(正则,忽略大小写)。字段名本身带这些后缀时按等值走,不会被拆开;字段缺失的行在 _ne / _nin 下算命中,其余算不命中
分页别名?_page=2&_per_page=10json-server 兼容写法,方便把现成的代码直接搬过来:_page + _per_page(只给 _page 时每页 10 条)、_start + _end(取 [start,end))、_limit / _skip / _sort / _order(等价于本家的 limit / skip / sortBy / order)。本家参数优先
select?select=id,title,price字段裁剪,逗号分隔;支持 address.city 这类点号路径,取出来的键用最后一段命名
任意字段名?category=beauty等值过滤。字段名和值都不区分大小写(?userid=3 等价于 ?userId=3),字段名也支持 address.city。多个条件之间是「且」,可叠加。不需要在「过滤字段」里填,直接拼在地址上就行
单条/m/products/1把 id 拼在路径后面,返回对象本身;不存在返回 404

过滤不到数据分两种,别搞混:

  • 字段存在、值没对上 → 正常返回 200 和 {"data":[],"total":0},说明数据里确实没有这个值;
  • 字段在数据集中不存在 → 返回 400,message 会写清楚哪个字段不存在、这个数据集有哪些字段可用。这是为了区别于「查到了 0 条」,免得你以为接口坏了。

翻页只看三个字段就够:page(第几页)、totalPages(一共几页)、hasMore(还有没有下一页),不用自己拿 total 去除 pageSize。

几个可以直接抄的组合:

?page=1&pageSize=5              # 第 1 页,每页 5 条
?page=3&pageSize=10             # 第 3 页,每页 10 条(跳过 20 条是后台算的)
?pageSize=0                     # 不分页,一次给全
?page=2                         # 只给页码,每页默认 10 条
?limit=5                        # 老写法:只要前 5 条
?limit=10&skip=20               # 老写法:第 3 页(每页 10 条)
?_page=3&_per_page=10           # 同上,json-server 写法
?_start=20&_end=30              # 取第 21~30 条
?q=phone&limit=5                # 先搜再分页
?category=beauty&sortBy=price&order=desc
?sortBy=category,price&order=asc,desc   # 先按类目升序,同类目按价格降序
?price_gte=100&price_lt=500     # 价格在 [100,500) 之间
?status_in=open,doing           # 状态是这两个之一
?title_like=*phone*             # 标题里含 phone(* 与 % 都是通配符)
?select=id,title,price          # 只要三个字段,响应更瘦
?sortBy=rating&order=desc&limit=3

增删改查:数据集就是一张小表

绑了数据集的地址不只会被动返回数据,它接得住写操作,而且写进去的行真的会留下来(落库,重启也在)。 所以「新增完跳详情页」「改完列表要变」「删完再查是 404」这些流程都能真联调,不用等后端:

方法地址干什么返回
GET/m/products列表(分页 / 搜索 / 排序见上一节)200 + { data, total, page, pageSize, totalPages, hasMore }
GET/m/products/1取单条200 + 对象本身;不存在 404
POST/m/products新增201 + 带 id 与 createdAt 的完整对象
PUT/m/products/1整份替换:请求体里没写的字段会被丢掉200 + 改后的对象(带 updatedAt)
PATCH/m/products/1局部修改:只改传进来的字段,其余保留200 + 改后的对象(带 updatedAt)
DELETE/m/products/1删除200 + 被删的那条(带 isDeleted 与 deletedOn);再取就是 404

三条容易踩的:

  • id 可以不带:不带则由数据集接着往下发号;带了就按你给的建(真实接口里 POST /pet 传 {id:101} 就是这么写的),撞号给 409,不会悄悄换个号让你以为建成功了;
  • PUT 和 PATCH 不一样:想改其中两个字段就用 PATCH,用 PUT 会把没写的字段清空;
  • 路径上别带 id 做新增:POST /m/products/1 是地址写错了,给 405。
# 新增:id 不用给
curl -X POST /m/u/{ns}/products -d '{"title":"新商品","price":99}'
# → 201  {"title":"新商品","price":99,"id":121,"createdAt":"2026-01-01 10:00:00"}

# 局部改:只改价格
curl -X PATCH /m/u/{ns}/products/121 -d '{"price":199}'
# → 200  {"id":121,"title":"新商品","price":199,...,"updatedAt":"..."}

# 删除
curl -X DELETE /m/u/{ns}/products/121
# → 200  {...,"isDeleted":true,"deletedOn":"..."}   再 GET 就是 404

想看一整套跑通的示例:/demo 里的「数据集:一个能增删改查的小数据库」那组, 11 条接口全是可直接调用的(列表分页 / 搜索排序 / 取单条 / 新增 / 整份改 / 局部改 / 删除, 以及四条「不限方法」的写法),页面右上角还能一键把演示数据恢复成最初的 20 条。

这组里写操作那几条(新增 / 整份改 / 局部改 / 删除)不会自动执行,页面上是个「执行这次请求」的按钮, 点了才真的发请求。因为它们会真改数据:删除跑一次那条就没了,要是进页面就自动跑, 想再看一次反而只剩 404。改乱了点「重置演示数据」回到最初的 20 条; 这份演示数据每整点也会自动重置一次,服务重启同样会重置。

动作可以不靠方法:写给发不出 PUT / PATCH / DELETE 的客户端

上面那张表是按请求方法区分动作的。绝大多数情况这就够了,但也有客户端发不出这些方法—— 老版本 Java 的 HttpURLConnection 只有 GET / POST,一些表单、网关、小程序环境同理。 这类客户端只能用 POST 打一切,POST /update-info/3 想表达的是"改第 3 条", 按方法却会被当成"新增"。

所以绑了数据集的响应上可以直接写明动作:在「数据集动作」里挑一个,请求方法就不再参与判断。

动作含义等价的方法
create新增一条POST
update整份替换:请求体里没写的字段会丢PUT
merge局部合并:只改传进来的字段,其余保留PATCH
delete删除一条DELETE
read查询(列表或单条)GET

几条要记的:

  • 只对绑了数据集的响应有意义;不写(默认)就还是按方法推断,行为与以前一模一样, 连响应头都不多一个。写了不认识的值也按"没写"处理,不会存出一个永远报错的规则;
  • 与方法冲突时以写明的为准,但会提醒你:响应头回 X-Mock-Dataset-Action: delete 与 X-Mock-Dataset-Action-Conflict: method=GET; byMethod=read; used=delete。 静默改掉语义最坑人:明明发的是 GET,数据却没了。 头里只放 ASCII(HTTP 头不允许非 ASCII,写中文会让严格客户端直接解析失败),说法由前端拼;
  • 写明了「删除」就真的 GET 也会删:这个功能靠的就是这一点,风险也在这。 别把这种地址随手分享出去,爬虫顺着链接爬一遍数据就没了;
  • 路径爱叫什么就叫什么:/create-info / /update-info/{id} 这类写法都能用, {id} 照常被当作资源 id。
# 只能用 POST 的客户端:写明动作是「整份替换」
curl -X POST /m/u/{ns}/update-info/3 -d '{"id":3,"city":"苏州"}'
# → 200 改后的对象,响应头里还带一句 X-Mock-Dataset-Action-Conflict

过滤字段:嵌套资源专用

「过滤字段」是可选的,只服务一种场景:路径里带变量的嵌套资源。它不填也照样能过滤,调用方直接带 ?userId=3 就会按该字段筛选,效果一样。填与不填的差别只在于:填了之后,路径变量会自动生效,调用方不用自己拼参数。

典型用法是嵌套资源。比如规则路径写 users/{userId}/posts、响应绑定 posts 数据集、过滤字段填 userId:

GET /m/users/3/posts     → 只返回 userId=3 的帖子
GET /m/users/3/posts?limit=5   → 在上面基础上再分页

要点:

  • 路径变量优先,其次查询参数,所以 /m/posts?userId=3 也能过滤(路径里没有 {userId} 时照样生效);
  • 请求里没带这个参数就不过滤,返回全部数据,不是返回空;
  • 比对忽略大小写;字段名写错会返回 400 并列出可用字段(不会再静默返回空数组);
  • 留空 = 不做这层过滤,调用方想过滤就自己拼 ?字段名=值;
  • 填的时候是从下拉里挑(选项就是所选数据集的字段),不用手输;字段名拼错不报错、只是永远筛不出东西,最难查;
  • 导入 OpenAPI 时会自动填:路径里带 {id} 且绑定了数据集,过滤字段就指定为 id; 路径变量名正好是实体字段的({username})就用那个字段。同时数据集的每一行都会补上 id 与 createdAt, 哪怕原文档里压根没声明这两个字段,否则路径变量接不上。

写操作真实作用于数据集(内存 + 自定义数据集会落盘):

POST   /m/products        # 新建,返回 201 和带 id 的完整对象(请求体里自带的 id 会被忽略,由系统分配)
PUT    /m/products/1      # 整份替换(没传的字段会丢)
PATCH  /m/products/1      # 字段合并(只改传了的字段)
DELETE /m/products/1      # 删除,返回带 isDeleted 的对象
  • 增删改都要求路径里带 id,也就是规则路径要写成 products/{id} 这种;只建了 products 一条规则的话,写操作会返回 400 提示需要 id;
  • 方法要放开:系统模板那两条规则的方法都选的是 ANY;
  • 改过的数据会真实生效(自建数据集会落盘,重启后仍在);模板数据集是共享的公共数据,写操作同样真实生效;
  • 系统自动生成的时间字段(新建的 createdAt、改过的 updatedAt、删除返回的 deletedOn) 格式统一为 yyyy-MM-dd HH:mm:ss,精确到秒。

小提示:列表(products)和单条(products/{id})是两条不同路径,需要建两条规则(方法都选 ANY、绑定同一个数据集),系统模板就是这么配的。

谁能看到哪个数据集:下拉里只有你自己创建的,别人的数据集不会出现在列表里(编号是随机分配的,等于凭证);系统模板数据集可以「从模板创建」复制一份后再绑定。选了「数据集」却没选具体数据集,保存时会直接拦下并提示是哪一处响应。