数据集
数据集(像真库一样)
把某条响应绑定到数据集,它返回的就不再是写死的文本,而是一个自带数据的 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=10 | json-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、绑定同一个数据集),系统模板就是这么配的。
谁能看到哪个数据集:下拉里只有你自己创建的,别人的数据集不会出现在列表里(编号是随机分配的,等于凭证);系统模板数据集可以「从模板创建」复制一份后再绑定。选了「数据集」却没选具体数据集,保存时会直接拦下并提示是哪一处响应。