feat: cluster-key-rate-limit support setting global rate limit thresholds for routes​ (#2262)

plugins/wasm-go/extensions/cluster-key-rate-limit/README.md

@@ -6,8 +6,12 @@ description: 基于 Key 集群限流插件配置参考
 
 ## 功能说明
 
-`cluster-key-rate-limit` 插件基于 Redis 实现集群限流，适用于需要跨多个 Higress Gateway 实例实现全局一致速率限制的场景。
-限流所使用的 Key 可以来源于 URL 参数、HTTP 请求头、客户端 IP 地址、消费者名称或 Cookie 中的 Key。
+`cluster-key-rate-limit` 插件基于 Redis 实现**集群级限流**，适用于需要跨多个 Higress Gateway 实例进行**全局一致速率限制**的场景。
+
+支持两种限流模式：
+
+- **规则级全局限流**：基于相同的 `rule_name` 和 `global_threshold` 配置，对自定义规则组设置全局限流阈值
+- **Key 级动态限流**：根据请求中的动态 Key（如 URL 参数、请求头、客户端 IP、Consumer 名称或 Cookie 字段）进行分组限流
 
 ## 运行属性
 
@@ -19,12 +23,22 @@ description: 基于 Key 集群限流插件配置参考
 | 配置项                  | 类型   | 必填 | 默认值 | 说明                                                                          |
 | ----------------------- | ------ | ---- | ------ |-----------------------------------------------------------------------------|
 | rule_name               | string | 是 | - | 限流规则名称，根据限流规则名称 + 限流类型 + 限流 key 名称 + 限流 key 对应的实际值来拼装 redis key             |
-| rule_items | array of object | 是   | -                 | 限流规则项，按照 rule_items 下的排列顺序，匹配第一个 rule_item 后命中限流规则，后续规则将被忽略                 |
+| global_threshold | Object | 否，`global_threshold` 或 `rule_items` 选填一项 | - | 对整个自定义规则组进行限流 |
+| rule_items | array of object | 否，`global_threshold` 或 `rule_items` 选填一项 | -                 | 限流规则项，按照 rule_items 下的排列顺序，匹配第一个 rule_item 后命中限流规则，后续规则将被忽略                 |
 | show_limit_quota_header | bool | 否 | false | 响应头中是否显示 `X-RateLimit-Limit`（限制的总请求数）和 `X-RateLimit-Remaining`（剩余还可以发送的请求数） |
 | rejected_code           | int | 否 | 429 | 请求被限流时，返回的 HTTP 状态码                                                         |
 | rejected_msg            | string | 否 | Too many requests | 请求被限流时，返回的响应体                                                               |
 | redis                   | object          | 是                                                           | -                 | redis 相关配置                                                                  |
 
+`global_threshold` 中每一项的配置字段说明。
+
+| 配置项           | 类型 | 必填                                                         | 默认值 | 说明               |
+| ---------------- | ---- | ------------------------------------------------------------ | ------ | ------------------ |
+| query_per_second | int  | 否，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中选填一项 | -      | 允许每秒请求次数   |
+| query_per_minute | int  | 否，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中选填一项 | -      | 允许每分钟请求次数 |
+| query_per_hour   | int  | 否，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中选填一项 | -      | 允许每小时请求次数 |
+| query_per_day    | int  | 否，`query_per_second`,`query_per_minute`,`query_per_hour`,`query_per_day` 中选填一项 | -      | 允许每天请求次数   |
+
 `rule_items` 中每一项的配置字段说明。
 
 | 配置项                | 类型            | 必填                   | 默认值 | 说明                                                                                                                                                       |
@@ -63,28 +77,39 @@ description: 基于 Key 集群限流插件配置参考
 
 ## 配置示例
 
+### 自定义规则组全局限流
+
+```yaml
+rule_name: routeA-global-limit-rule
+global_threshold:
+  query_per_minute: 1000 # 自定义规则组每分钟最多1000次请求
+redis:
+  service_name: redis.static
+show_limit_quota_header: true
+```
+
 ### 识别请求参数 apikey，进行区别限流
 
 ```yaml
-rule_name: default_rule
+rule_name: routeA-request-param-limit-rule
 rule_items:
-- limit_by_param: apikey
-  limit_keys:
-  - key: 9a342114-ba8a-11ec-b1bf-00163e1250b5
-    query_per_minute: 10
-  - key: a6a6d7f2-ba8a-11ec-bec2-00163e1250b5
-    query_per_hour: 100
-- limit_by_per_param: apikey
-  limit_keys:
-  # 正则表达式，匹配以 a 开头的所有字符串，每个 apikey 对应的请求 10qds
-  - key: "regexp:^a.*"
-    query_per_second: 10
-  # 正则表达式，匹配以 b 开头的所有字符串，每个 apikey 对应的请求 100qd
-  - key: "regexp:^b.*"
-    query_per_minute: 100
-  # 兜底用，匹配所有请求，每个 apikey 对应的请求 1000qdh
-  - key: "*"
-    query_per_hour: 1000
+  - limit_by_param: apikey
+    limit_keys:
+      - key: 9a342114-ba8a-11ec-b1bf-00163e1250b5
+        query_per_minute: 10
+      - key: a6a6d7f2-ba8a-11ec-bec2-00163e1250b5
+        query_per_hour: 100
+  - limit_by_per_param: apikey
+    limit_keys:
+      # 正则表达式，匹配以 a 开头的所有字符串，每个 apikey 对应的请求 10qds
+      - key: "regexp:^a.*"
+        query_per_second: 10
+      # 正则表达式，匹配以 b 开头的所有字符串，每个 apikey 对应的请求 100qd
+      - key: "regexp:^b.*"
+        query_per_minute: 100
+      # 兜底用，匹配所有请求，每个 apikey 对应的请求 1000qdh
+      - key: "*"
+        query_per_hour: 1000
 redis:
   service_name: redis.static
 show_limit_quota_header: true
@@ -93,25 +118,25 @@ show_limit_quota_header: true
 ### 识别请求头 x-ca-key，进行区别限流
 
 ```yaml
-rule_name: default_rule
+rule_name: routeA-request-header-limit-rule
 rule_items:
-- limit_by_header: x-ca-key
-  limit_keys:
-  - key: 102234
-    query_per_minute: 10
-  - key: 308239
-    query_per_hour: 10
-- limit_by_per_header: x-ca-key
-  limit_keys:
-  # 正则表达式，匹配以 a 开头的所有字符串，每个 apikey 对应的请求 10qds
-  - key: "regexp:^a.*"
-    query_per_second: 10
-  # 正则表达式，匹配以b开头的所有字符串，每个 apikey 对应的请求 100qd
-  - key: "regexp:^b.*"
-    query_per_minute: 100
-  # 兜底用，匹配所有请求，每个 apikey 对应的请求 1000qdh
-  - key: "*"
-    query_per_hour: 1000            
+  - limit_by_header: x-ca-key
+    limit_keys:
+      - key: 102234
+        query_per_minute: 10
+      - key: 308239
+        query_per_hour: 10
+  - limit_by_per_header: x-ca-key
+    limit_keys:
+      # 正则表达式，匹配以 a 开头的所有字符串，每个 apikey 对应的请求 10qds
+      - key: "regexp:^a.*"
+        query_per_second: 10
+      # 正则表达式，匹配以b开头的所有字符串，每个 apikey 对应的请求 100qd
+      - key: "regexp:^b.*"
+        query_per_minute: 100
+      # 兜底用，匹配所有请求，每个 apikey 对应的请求 1000qdh
+      - key: "*"
+        query_per_hour: 1000
 redis:
   service_name: redis.static
 show_limit_quota_header: true
@@ -120,19 +145,19 @@ show_limit_quota_header: true
 ### 根据请求头 x-forwarded-for 获取对端 IP，进行区别限流
 
 ```yaml
-rule_name: default_rule
+rule_name: routeA-client-ip-limit-rule
 rule_items:
-- limit_by_per_ip: from-header-x-forwarded-for
-  limit_keys:
-  # 精确 IP
-  - key: 1.1.1.1
-    query_per_day: 10
-  # IP 段，符合这个 IP 段的 IP，每个 IP 100qpd
-  - key: 1.1.1.0/24
-    query_per_day: 100
-  # 兜底用，即默认每个 IP 1000 qpd
-  - key: 0.0.0.0/0
-    query_per_day: 1000
+  - limit_by_per_ip: from-header-x-forwarded-for
+    limit_keys:
+      # 精确 IP
+      - key: 1.1.1.1
+        query_per_day: 10
+      # IP 段，符合这个 IP 段的 IP，每个 IP 100qpd
+      - key: 1.1.1.0/24
+        query_per_day: 100
+      # 兜底用，即默认每个 IP 1000 qpd
+      - key: 0.0.0.0/0
+        query_per_day: 1000
 redis:
   service_name: redis.static
 show_limit_quota_header: true
@@ -141,25 +166,25 @@ show_limit_quota_header: true
 ### 识别 consumer，进行区别限流
 
 ```yaml
-rule_name: default_rule
+rule_name: routeA-consumer-limit-rule
 rule_items:
-- limit_by_consumer: ''
-  limit_keys:
-  - key: consumer1
-    query_per_second: 10
-  - key: consumer2
-    query_per_hour: 100
-- limit_by_per_consumer: ''
-  limit_keys:
-  # 正则表达式，匹配以 a 开头的所有字符串，每个 consumer 对应的请求 10qds
-  - key: "regexp:^a.*"
-    query_per_second: 10
-  # 正则表达式，匹配以 b 开头的所有字符串，每个 consumer 对应的请求 100qd
-  - key: "regexp:^b.*"
-    query_per_minute: 100
-  # 兜底用，匹配所有请求，每个 consumer 对应的请求 1000qdh
-  - key: "*"
-    query_per_hour: 1000     
+  - limit_by_consumer: ''
+    limit_keys:
+      - key: consumer1
+        query_per_second: 10
+      - key: consumer2
+        query_per_hour: 100
+  - limit_by_per_consumer: ''
+    limit_keys:
+      # 正则表达式，匹配以 a 开头的所有字符串，每个 consumer 对应的请求 10qds
+      - key: "regexp:^a.*"
+        query_per_second: 10
+      # 正则表达式，匹配以 b 开头的所有字符串，每个 consumer 对应的请求 100qd
+      - key: "regexp:^b.*"
+        query_per_minute: 100
+      # 兜底用，匹配所有请求，每个 consumer 对应的请求 1000qdh
+      - key: "*"
+        query_per_hour: 1000
 redis:
   service_name: redis.static
 show_limit_quota_header: true 
@@ -168,7 +193,7 @@ show_limit_quota_header: true
 ### 识别 Cookie 中的键值对，进行区别限流
 
 ```yaml
-rule_name: default_rule
+rule_name: routeA-cookie-limit-rule
 rule_items:
   - limit_by_cookie: key1
     limit_keys: