频率限制 / Echo / 接口状态
请求频率限制
为了防止服务被拖垮,也为了让每个接口都有稳定的承载上限,mock 调用有两道限流,都会被检查:
| 维度 | 默认 | 含义 |
|---|---|---|
| 按调用方 IP(mock 接口) | 每秒 5 次 | 同一个 IP 每秒最多调用多少次 mock 接口。管的是「一个人别把服务打满」,多个同事共用一个出口 IP 时额度是共享的 |
| 按调用方 IP(HTTP Echo) | 每秒 50 次 | Echo 是公共服务(探活、练手、看返回结构),调用量远大于普通 mock,单独一份额度、默认放宽。这条由服务端配置固定 |
| 全接口总量(HTTP Echo) | 每秒 200 次 | 所有调用方合计每秒的 Echo 上限——每个 IP 都没超线时,加起来的量也可能把服务打满,这道总闸管的就是它。管理员可在后台「系统信息」面板动态调整,改完立即生效,重启不丢 |
| 按接口 | 每秒 5 次 | 单个接口每秒最多被调多少次,不管谁来调。管的是「这个接口自己的承载上限」 |
两道都是令牌桶,允许少量突发(比如页面一次并发发几个请求不会被误伤)。控制台页面、接口管理、静态资源不参与限流,所以后台操作不会因为压测而卡住。
接口的额度按这个顺序定:接口自己配的 > 所有者账号的配额 > 服务端默认。创建 / 编辑接口时展开「调用频率限制」就能单独设,留空表示跟随账号配额,填 0 表示这个接口不限流。
超过额度的请求不再进入规则匹配(接口那一道则是不再做渲染 / 查数据集),直接被拦下并返回 429。这不是接口出错,也不是你的规则配错了。
被拦下时能看到什么
响应头上会带 Retry-After(还要等几秒);响应体是标准 JSON,一句话说清原因、上限和要等多久:
{
"code": 429,
"message": "请求过于频繁:该接口每秒最多调用 5 次,请 1 秒后重试",
"retryAfter": 1,
"limitPerSecond": 5,
"scope": "api",
"method": "GET",
"path": "/m/orders"
}
| 字段 | 含义 |
|---|---|
message | 一句话说明上限和要等多久,直接给人看 |
retryAfter | 还要等几秒,与响应头 Retry-After 一致;程序里直接拿它做退避重试 |
limitPerSecond | 当前生效的每秒上限 |
scope | api = 被接口自己那道拦下;echo = 被 Echo 的 IP 限流拦下;echo-total = 被 Echo 的全接口总闸拦下(不是针对你,是所有调用方的量加起来到顶了);mock 或没有这个字段就是被 mock 的 IP 那道拦的 |
method / path | 被拦下的是哪个请求,方便对号入座 |
接下来怎么办
- 降速:批量 / 循环调用时把并发降下来,或在两次请求之间加一点间隔(比如 200ms);
- 退避重试:程序里读到 429 时,按
retryAfter秒等待后再发一次,不要立刻重试——立刻重试只会被继续拦; - 查得到记录:被限流的请求也会记进调用日志(状态
429、标记「被限流拦截」);为免刷屏,同一个 IP 每秒最多记一条。 要让它在你的「调用日志」里出现,请求得带上你的身份——登录会话 Cookie,或你自己账号的 API Key (Authorization: Bearer amk_xxx)。什么都不带的匿名请求照样记,但挂在「没有归属」名下,只有后台看得到: 同一个出口 IP 后面可能是任何人,凭 IP 认不出是谁发的; - 需要更高吞吐:要做压测级别的量(几百 QPS 以上),建议自己部署一份实例,按需调整上限。
小提示:多个同事在同一出口 IP 后面(比如共用一个 NAT 或同一个 CI 机器)时,额度是按 IP 共享的,一个人的压测会影响同一出口的其他人。
HTTP Echo
对着 /echo 发什么,它就原样回什么。调第三方回调(Webhook)时最有用: 对方到底发了哪些头、正文长什么样、签名在哪,填个 Echo 地址当回调,一发就能看到。
POST /echo/order/paid
Content-Type: application/json
{"event":"paid","id":9}
响应里会把这次请求完整摊开:
| 字段 | 含义 |
|---|---|
method / path / uri | 方法、路径、带查询串的完整 URI |
query / form | 查询参数;表单提交时另有解好的字段 |
headers / cookies | 请求头(键名统一小写)、拆好的 Cookie |
body / bodySize | 请求体原文与字节数 |
json | 请求体是 JSON 时额外给出解析后的结构,不用自己再去反转义 |
clientIp / host / scheme | 来源 IP、Host、是 http 还是 https |
time / timestamp | 服务端收到的时间 |
子路径随便写
/echo 后面可以接任意路径:/echo/order/paid、/echo/wechat/callback 都收。 这样在调用日志里能一眼分出是哪一类回调——很多平台允许带业务标识的回调地址,正好用上。
带上你的命名空间,日志才找得到
Echo 不是规则,没有归属。不带标识调用的话,这条日志不属于任何人,控制台的「调用日志」里翻不到它,而排查回调时最想看的就是它。
把子路径的第一段写成你自己的命名空间,这次调用就记到你名下:
/echo/你的命名空间/order/paid
命名空间在控制台「我的账号」里看得到,也可以自己改。认出来之后, 日志的归属就是你,控制台的「我的调用记录」里选类型 → HTTP Echo 就能筛出来; 认不出来(那段不是任何人的命名空间)就当普通子路径放过,不报错。
在浏览器里带着登录态调用也一样归你,所以最简单的用法是登录后直接打 /echo/xxx。
三个可选参数
| 参数 | 作用 |
|---|---|
?status=500 | 指定响应状态码,验证调用方的失败分支与重试逻辑 |
?delay=1500 | 延迟 1500 毫秒再回(上限 30 秒),验证超时处理 |
?format=text | 回纯文本(只回请求体);html 给浏览器直接打开看的版式 |
Echo 收到的请求也会记进「调用日志」,名字是 HTTP Echo,事后要回看同样查得到, 日志列表上的类型筛选选「HTTP Echo」就只看这一类。 归属怎么定:带着登录会话打的算你这个账号的;没登录时,可以把命名空间写进路径
(/echo/你的命名空间/order/paid)明确指定记到谁名下;两者都没有就是「未认领」, 不会出现在任何人的「我的调用日志」里。 它同样受请求频率限制约束。
接口状态(跨请求记忆)
mock 天生是无状态的:进来一个请求、吐一段响应、结束。可真实接口不是这样, 下单接口建出来的订单号,查询接口得能查到。接口状态补的就是这段记忆。
做法分两步:在响应里写,在之后的响应里读。
写:响应里的「状态写入」
编辑接口时展开响应区的状态写入,一行一个 键: 值,值里可以用任意
模板变量:
lastId: {{request.body.id}}
counter: {{inc({{state.counter}})}}
global.token: {{faker.string.uuid}}
命中这条响应之后,这些键值就存下来了。键名写成 global.xxx 表示存到全站共享的那份, 几条不同接口可以共用;值算出来是空串,等于把这个键删掉。
读:{{state.键}}
| 写法 | 含义 |
|---|---|
{{state.键}} | 读这条接口自己写下的值(按接口分作用域,互不干扰) |
{{state.global.键}} | 读全站共享的那份 |
{{state.键|默认值}} | 还没写过时的兜底值,跟其它变量一样 |
{{inc({{state.counter}})}} | 加一:第一次拿到 1,适合做计数器 |
{{add({{state.total}},10)}} | 求和;{{sub(a,b)}} 相减,做库存递减之类 |
顺序:先返回旧值,再写入新值
一次调用里的次序是先渲染响应、后写状态。所以本次响应读到的仍是上一次的值, 新值留给下一次,"先建后查"靠的就是这个次序。举个例子,写入
lastId: {{request.query.v}}、响应体是 {{state.lastId|空}}:
第 1 次 ?v=A → {"lastId":"空"} (还没写过)
第 2 次 ?v=B → {"lastId":"A"} (读到上一次写的)
第 3 次 ?v=C → {"lastId":"B"}
有效期:别让它无限长下去
状态是"写了就忘"的东西:接口删了、调试停了,键值却还在表里。所以每条都能带一个有效期:
- 控制台「接口状态」面板里点某一行的有效期,可以单独设成 10 分钟 / 1 小时 / 1 天 / 7 天, 也可以改回永不过期;
- 服务端还能配一个默认值(
state-ttl),没单独指定的键都按它走; - 另有总量上限(
state-max-entries),超了就淘汰最久没动过的。 有效期管"每条活多久",这条管"总共能有多少",两者都要有。
到期之后 {{state.键}} 读出来就是空值(跟没写过一样), 表里那条记录由后台每 10 分钟回收一次;面板上的回收已过期可以立刻清一遍。
状态存在数据库里,重启不丢。想看看现在记住了什么、或者清零重来, 去控制台「导入导出」页最下方的接口状态面板。
快照与回滚
快照就是给"手一抖"留的退路:把当时的规则与数据集整包存一份,之后随时倒回去。
什么时候会自动存
- 用
replace模式导入之前(会先清空现有规则); - 整站清空之前;
- 执行回滚之前——回滚本身也是破坏性操作,先给当前状态留一份。
自动存的那几份在列表里标成「自动」,数量超上限时优先牺牲它们; 手动打了名字的排在后面,因为那是你有意留的。
恢复 与 回滚
| 操作 | 做什么 | 什么时候用 |
|---|---|---|
| 恢复 | 把快照里的接口追加回来,路径撞了的自动加后缀 | 只想捞回其中几条 |
| 回滚 | 先清空现有的,再整体倒回那一份 | 整站回到那个时刻 |
入口在控制台「导入导出」页的快照面板:填个名字点「打一份快照」, 列表里每一份都能单独恢复、回滚或删除。默认保留最近 30 份。