接口调频

接口调频对单个 Open API operation 生效：按 (appkey, operationId) 维护 1 秒滑动窗口，超过 QPS 返回 1008 并附带 Retry-After: 1。默认未配置即不限频。

概念​

项值
窗口长度1000ms 滑动窗口
单应用最多覆盖512 个 operation
QPS 范围0-10000；0 表示该接口不限频
超限响应HTTP 429，code=1008，Retry-After: 1
与协议频率的区别

协议声明的 sendRatePerMinute 与配额 messageRatePerMinute 当前都未在服务端强制；唯一生效的接口级限流是本页配置。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#ratelimit。
  • 已设置 X-Admin-Secret（默认 dev-admin；控制台会保存在浏览器 localStorage 的 im.admin.secret）。
  • 已创建应用并在控制台顶部选中应用（模块接口路径都带 {appkey}）。

步骤​

  1. 查看当前覆盖
    enabled 为 false 表示没有任何覆盖，即全放行。
  2. 设置覆盖（整体覆盖）

    提交 overrides 映射；未提交的 operation 恢复不限频。

  3. 验证 429

    对同一 operation 在 1 秒内发起超过 QPS 的请求，应返回 429 + Retry-After。

参数表​

操作方法与路径请求体
查询GET /api/admin/apps/{appkey}/ratelimit—
设置POST /api/admin/apps/{appkey}/ratelimit{overrides:{"operationId":qps}}

示例​

把单聊发布限制为 10 QPS，再解除​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/ratelimit" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"overrides":{"message.private.publish":10}}'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/ratelimit" \
  -H 'X-Admin-Secret: dev-admin'

# qps=0 = 不限频；空对象 = 全部解除
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/ratelimit" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"overrides":{}}'

常见问题​

为什么设置了还没限流？​

确认 operationId 拼写与调用路径一致（限流键是 operationId，不是 URL）。

客户端 WS 发送会被限吗？​

不会。调频只作用于 Open API 分发；客户端长连接有自己的协议频率声明（未强制）。

429 应该怎么重试？​

读取 Retry-After（当前固定 1 秒）后重试；不要立即重试造成放大。

相关链接​