limit-count插件
更新时间 2026-04-21 15:48:57
最近更新时间: 2026-04-21 15:48:57
本文将详细介绍limit-count插件功能、配置和使用。
功能说明
limit-count 插件使用固定时间窗口算法，主要用于限制单个客户端在指定的时间范围内对服务的总请求数，并且会在 HTTP 响应头中返回剩余可以请求的个数.
配置字段
| 名称 | 类型 | 填写要求 | 默认值 | 有效值 | 描述 |
|---|---|---|---|---|---|
| count | integer | 必填 | count> 0 | 每个客户端在指定时间窗口内的总请求数量阈值。 | |
| time_window | integer | 必填 | time_window> 0 | 时间窗口的大小（以秒为单位）。超过该属性定义的时间，则会重新开始计数。 | |
| rejected_code | integer | 可选 | 503 | [200,...,599] | 当请求超过阈值被拒绝时，返回的 HTTP 状态码。 |
| key_type | string | 可选 | "var" | ["var", "var_combination", "constant"] | key 的类型。 |
| key | string | 可选 | "remote_addr" | 用来做请求计数的依据。如果 key_type 为 constant，那么 key 会被当作常量；如果 key_type 为 var，那么 key 会被当作变量；如果 key_type 为 var_combination，那么 key 会被当作变量组合，如 $remote_addr $consumer_name，插件会同时受 $remote_addr 和 $consumer_name 两个变量的约束；如果 key 的值为空，$remote_addr 会被作为默认 key。 | |
| rejected_msg | string | 可选 | 非空 | 当请求超过阈值被拒绝时，返回的响应体。 | |
| allow_degradation | boolean | 可选 | false | 当插件功能临时不可用时（例如 Redis 超时），当设置为 true 时，则表示可以允许插件降级并进行继续请求的操作。 | |
| show_limit_quota_header | boolean | 可选 | true | 当设置为 true 时，在响应头中显示 X-RateLimit-Limit（限制的总请求数）和 X-RateLimit-Remaining（剩余还可以发送的请求数）字段。 |
配置示例
limit-count 使用示例
count: 2
time_window: 60
rejected_code: 503
key_type: "var"
key: "remote_addr"根据该配置场景，其限制了 60 秒内请求只能访问 2 次。请求以下路由
curl -i http://example.com/index.html在执行测试命令的前两次都会正常访问。其中响应头中包含了 X-RateLimit-Limit 和 X-RateLimit-Remaining 和 X-RateLimit-Reset 字段，分别代表限制的总请求数和剩余还可以发送的请求数以及计数器剩余重置的秒数：
HTTP/1.1 200 OK
......
X-RateLimit-Limit: 2
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 58当第三次进行测试访问时，会收到包含 503 HTTP 状态码的响应头，目前在拒绝的情况下，也会返回相关的头，表示插件生效：
HTTP/1.1 503 Service Temporarily Unavailable
......
X-RateLimit-Limit: 2
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 58配置模板
基础配置案例
# [必填]时间窗口内的请求数量阈值。
count: 30
# [必填]时间窗口的大小（以秒为单位）
time_window: 60
# [可选]请求超过阈值被拒绝时，返回的 HTTP 状态码
#rejected_code: 429
# [可选]key 的类型
#key_type: "var"
# [可选]用来做请求计数的依据
#key: "remote_addr"
# [可选]当设置rejected_msg时，非空。默认可不填
# rejected_msg: "Requests are too frequent, please try again later."
# [可选]当限流插件功能临时不可用时（例如，Redis 超时）是否允许请求继续。默认 false
#allow_degradation: false
# [可选]是否在响应头中显示 X-RateLimit-Limit 和 X-RateLimit-Remaining （限制的总请求数和剩余还可以发送的请求数），默认 true
#show_limit_quota_header: true
