跳到主要内容

graphql-limit-count

graphql-limit-count 插件使用固定窗口限制 GraphQL 查询（Queries）和变更（Mutations）的累计成本。查询深度是默认成本，保持了插件的原有行为。complexity 和 node_quantifier 策略用于度量文档要求执行的工作量，在 APISIX 和 API7 企业版中均可用。

在 GraphQL 中，深度是指查询或变更中的嵌套层级数。以下是一个深度为 3 的查询示例：

{
  a {
    b {
      c
    }
  }
}

使用默认深度策略时，插件会在每个时间间隔内消耗深度配额。例如，如果 30 秒间隔内的配额为 4，则深度为 3 的请求会被允许，并剩余 1。同一间隔内深度为 2 的请求会被拒绝。

该插件接受包含 query 字段的 JSON 请求体，或正文直接包含 GraphQL 文档且媒体类型为 application/graphql 的 POST 请求。片段（fragment）会计入查询深度。不支持的方法返回 405 Method Not Allowed；无法读取、格式错误或无效的 GraphQL 请求返回 400 Bad Request。

APISIX 和 API7 Gateway 默认最多读取 1 MiB 的 GraphQL 请求数据。若要调整该限制，请在 config.yaml 中配置 graphql.max_size 并重新加载网关：

config.yaml
graphql:
  max_size: 1048576

本地限速与基于 Redis 的限速​

graphql-limit-count 插件支持两种限速模式：

  • 本地限速：每个网关实例独立实施限速。每个实例维护自己的计数器，因此当流量分散到多个实例时，实际限额约为“限额 × 实例数”。未设置 policy 或将其设置为 local 时，这是默认模式。
  • 基于 Redis 的限速：通过 Redis 在所有网关实例之间共享限额。所有实例共享同一配额，因此配置的限额适用于全部网关实例。

查询成本​

complexity、node_quantifier 策略及其支持字段在 API7 企业版 3.10.6 和 APISIX 3.19.0 中引入。

默认情况下，一个请求按其查询深度计费。cost_strategy 可以选择不同的成本模型，使请求按其向上游要求的工作量消耗配额：

  • depth 按选择集的嵌套深度计费。这是该插件一直以来的行为，也仍是默认值，因此升级后已有配置的行为不变。
  • complexity 根据查询解析的节点计算原始分数。每个节点贡献的分数为 (其所有子节点之和) × mul + add，其中 add 与 mul 默认为 1。
  • node_quantifier 只根据匹配成本装饰能在 mul_arguments 中找到可用量词的节点计算原始分数。例如，带有 mul_arguments: ["first"] 的装饰会把 first: 10 作为更深层量化节点的乘数。如果没有节点同时具备匹配装饰和可用量词，文档的原始分数为 0。默认 score_factor 会产生计费成本 1；执行 0.01 调整后，大于 100 的系数会提高该成本。

插件会把策略原始分数转换为计入配额的整数。对于 complexity 和 node_quantifier，它会先给原始分数加 0.01，再应用 score_factor 并向上取整。因此，使用默认系数 1 时，原始整数分数 3 会按 4 计费。depth 策略不执行 0.01 调整，但仍会应用系数并向上取整。

max_cost 会在查询到达上游前，以 403 Forbidden 拒绝计费成本超过配置值的查询。插件会先计入配额，再执行该检查，因此因成本过高而被拒绝的查询仍会消耗计算出的配额。启用 show_limit_quota_header 时，X-Graphql-Query-Cost 会报告该数值。

resolve_variables 默认开启，此时插件会先解析已提供的 GraphQL 变量、操作声明的变量默认值，以及上游 schema 中的参数默认值，再计算成本。关闭它会把 first: $n 当作未提供参数，从而可能低估通过变量提交量词的查询成本。

把成本装饰与查询匹配需要上游 schema。APISIX 会在第一次处理适用请求时内省服务并缓存 schema。上游 schema 发生变化后，请重新加载 APISIX。当内省端点不是上游本身时，请设置 introspection_endpoint；当该端点需要凭据时，请设置 introspection_headers。

没有成本装饰的服务所绑定的路由，或未绑定服务的路由，不会触发内省。在这种情况下，complexity 使用默认权重计算每个节点，而 node_quantifier 的原始分数为 0。其计费成本遵循上述调整和缩放规则。

成本装饰​

一条装饰用于调整上游 schema 中某个位置对成本的贡献。装饰在服务上以 graphql_cost_decorations 管理，因此由该服务下的所有路由共享，并且无需编辑承载该插件的路由即可修改。

一条装饰指定一个 field_path，它可以标识 GraphQL 类型（如 Product）、类型加字段（如 Product.name），也可以标识一条字段链（如 Query.products.nodes）。装饰会调整它匹配到的节点：

字段作用
add_value加到该节点自身的成本上。
mul_value对该节点子节点的成本做乘法。
add_arguments指定若干参数，其取值会加到该节点自身的成本上。
mul_arguments指定若干参数，其取值会乘以后代成本。在 node_quantifier 策略下，该乘数会传递到更深层的量化节点。

同一个服务中的每个 field_path 都必须唯一。请串行执行针对同一服务的并发装饰写入操作，以保持唯一性。

在 APISIX 中，装饰是独立的 Admin API 资源，而不是服务请求体中的字段。将 SERVICE_ID 设为现有服务 ID，然后创建或替换装饰：

curl "http://127.0.0.1:9180/apisix/admin/services/${SERVICE_ID}/graphql_cost_decorations/products-page-size" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "field_path": "Query.products",
    "add_value": 1,
    "mul_value": 1,
    "mul_arguments": ["first"]
  }'

❶ field_path 指定需要装饰的字段。请根据上游 schema 调整该值。

❷ add_value 和 mul_value 使用默认值 1。

❸ mul_arguments 使用 first 作为乘数。在 complexity 策略下，它会乘以选中子节点的成本；在 node_quantifier 策略下，它会乘以更深层的量化节点，而不是节点自身的成本。

使用 GET 列出或获取装饰，使用 PATCH 更新装饰，使用 DELETE 删除装饰。有关服务及相关 Admin API 操作，请参阅服务文档。

示例​

以下示例使用 GitHub GraphQL API 端点作为上游，并演示了如何在不同场景下配置 graphql-limit-count。

要进行后续操作，请创建一个 GitHub 个人访问 Token，并为你想要交互的资源配置适当的权限范围。

基于远程地址进行速率限制​

以下示例演示了如何通过单个变量 remote_addr 对 GraphQL 请求进行速率限制。

创建一个启用了 graphql-limit-count 插件的路由，配置为每个远程地址在 30 秒窗口内允许的深度配额为 2：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "graphql-limit-count-route",
    "uri": "/graphql",
    "plugins": {
      "graphql-limit-count": {
        "count": 2,
        "time_window": 30,
        "rejected_code": 429,
        "key_type": "var",
        "key": "remote_addr",
        "policy": "local"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "pass_host": "node",
      "scheme": "https",
      "nodes": {
        "api.github.com:443": 1
      }
    }
  }'

使用 GraphQL 查询进行验证​

发送一个深度为 2 的 GraphQL 查询请求进行验证：

curl -i "http://127.0.0.1:9080/graphql" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${GH_ACCESS_TOKEN}" \
  -d '{"query": "query {viewer{login}}"}'

你应看到 HTTP/1.1 200 OK 响应及对应的响应体。

该请求已消耗了时间窗口内允许的所有配额。如果你在同一个 30 秒时间间隔内再次发送请求，应该会收到 HTTP/1.1 429 Too Many Requests 响应，表明请求超过了配额阈值。

使用 GraphQL 变更进行验证​

你也可以发送一个深度为 3 的 GraphQL 变更请求进行验证：

curl -i "http://127.0.0.1:9080/graphql" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${GH_ACCESS_TOKEN}" \
  -d '{"query": "mutation AddReactionToIssue {addReaction(input:{subjectId:\"MDU6SXNzdWUyMzEzOTE1NTE=\",content:HOORAY}) {reaction {content} subject {id}}}"}'

你会随时看到 HTTP/1.1 429 Too Many Requests 响应，因为深度 3 总是超过深度 2 的配额。

基于远程地址和消费者名称进行速率限制​

以下示例演示了如何通过变量组合 remote_addr 和 consumer_name 对 GraphQL 请求进行速率限制。它允许每个远程地址和每个消费者在 30 秒窗口内的深度配额为 2。

创建消费者 john：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "john"
  }'

为该消费者创建 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-key-auth",
    "plugins": {
      "key-auth": {
        "key": "john-key"
      }
    }
  }'

创建第二个消费者 jane：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "jane"
  }'

为该消费者创建 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/jane/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-jane-key-auth",
    "plugins": {
      "key-auth": {
        "key": "jane-key"
      }
    }
  }'

创建一个启用了 key-auth 和 graphql-limit-count 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "graphql-limit-count-route",
    "uri": "/graphql",
    "plugins": {
      "key-auth": {},
      "graphql-limit-count": {
        "count": 2,
        "time_window": 30,
        "rejected_code": 429,
        "policy": "local",
        "key_type": "var_combination",
        "key": "$remote_addr $consumer_name"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "pass_host": "node",
      "scheme": "https",
      "nodes": {
        "api.github.com:443": 1
      }
    }
  }'

❶ key-auth：在路由上启用密钥认证。

❷ key_type：设置为 var_combination，将 key 解释为变量组合。

❸ key: 设置为 $remote_addr $consumer_name 以根据远程地址和消费者应用限速配额。

作为消费者 jane 发送一个深度为 2 的 GraphQL 查询请求：

curl -i "http://127.0.0.1:9080/graphql" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${GH_ACCESS_TOKEN}" \
  -H 'apikey: jane-key' \
  -d '{"query": "query {viewer{login}}"}'

你应看到 HTTP/1.1 200 OK 响应及对应的响应体。

此请求已消耗了该时间窗口的所有配额。如果你在同一个 30 秒时间间隔内再次以消费者 jane 的身份发送相同的请求，应该会收到 HTTP/1.1 429 Too Many Requests 响应，表明请求超过了配额阈值。

在同一个 30 秒时间间隔内以消费者 john 的身份发送相同的请求：

curl -i "http://127.0.0.1:9080/graphql" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${GH_ACCESS_TOKEN}" \
  -H 'apikey: john-key' \
  -d '{"query": "query {viewer{login}}"}'

你应该会看到带有相应响应体的 HTTP/1.1 200 OK 响应，表明该请求未被限速。

在同一个 30 秒时间间隔内再次以消费者 john 的身份发送相同的请求，你应该会收到 HTTP/1.1 429 Too Many Requests 响应。

这验证了插件是根据变量组合 remote_addr 和 consumer_name 进行速率限制的。

在路由间共享配额​

以下示例演示了如何通过配置 graphql-limit-count 插件的 group 字段，在多个路由之间共享 GraphQL 速率限制配额。

请注意，同一 group 的 graphql-limit-count 插件配置应完全相同。为了避免更新异常和重复配置，你可以创建一个启用了 graphql-limit-count 插件的服务（Service）供路由连接。

创建一个服务：

curl "http://127.0.0.1:9180/apisix/admin/services" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "graphql-limit-count-service",
    "plugins": {
      "graphql-limit-count": {
        "count": 2,
        "time_window": 30,
        "rejected_code": 429,
        "policy": "local",
        "group": "graphql-srv1"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "pass_host": "node",
      "scheme": "https",
      "nodes": {
        "api.github.com:443": 1
      }
    }
  }'

创建两个路由并将它们的 service_id 配置为 graphql-limit-count-service，以便它们共享相同的插件和上游配置：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "graphql-limit-count-route-1",
    "service_id": "graphql-limit-count-service",
    "uri": "/graphql1",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/graphql"
      }
    }
  }'
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "graphql-limit-count-route-2",
    "service_id": "graphql-limit-count-service",
    "uri": "/graphql2",
    "plugins": {
      "proxy-rewrite": {
        "uri": "/graphql"
      }
    }
  }'
备注

proxy-rewrite 插件用于将 URI 重写为 /graphql，使请求转发到正确的端点。

发送一个深度为 2 的 GraphQL 查询请求到路由 /graphql1：

curl -i "http://127.0.0.1:9080/graphql1" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${GH_ACCESS_TOKEN}" \
  -d '{"query": "query {viewer{login}}"}'

你应看到 HTTP/1.1 200 OK 响应及对应的响应体。

在同一个 30 秒时间间隔内发送相同的深度为 2 的查询到路由 /graphql2：

curl -i "http://127.0.0.1:9080/graphql2" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${GH_ACCESS_TOKEN}" \
  -d '{"query": "query {viewer{login}}"}'

你应该会收到 HTTP/1.1 429 Too Many Requests 响应，这验证了两个路由共享相同的限速配额。

使用 Redis 服务器在网关实例间共享配额​

以下示例使用 Redis 服务器，让多个网关实例共享同一 GraphQL 限速配额。

在网关组中创建一个具有以下配置的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "graphql-limit-count-route",
    "uri": "/graphql",
    "plugins": {
      "graphql-limit-count": {
        "count": 2,
        "time_window": 30,
        "rejected_code": 429,
        "key": "remote_addr",
        "policy": "redis",
        "redis_host": "192.168.xxx.xxx",
        "redis_port": 6379,
        "redis_password": "p@ssw0rd",
        "redis_database": 1
      }
    },
    "upstream": {
      "type": "roundrobin",
      "pass_host": "node",
      "scheme": "https",
      "nodes": {
        "api.github.com:443": 1
      }
    }
  }'

❶ policy: 设置为 redis 以使用 Redis 实例进行限速。

❷ redis_host: 设置为 Redis 实例的 IP 地址。

❸ redis_port: 设置为 Redis 实例的监听端口。

❹ redis_password: 设置为 Redis 实例的密码（如果有）。

❺ redis_database: 设置为 Redis 实例中的数据库编号。

发送一个深度为 2 的 GraphQL 查询请求到一个网关实例：

curl -i "http://127.0.0.1:9080/graphql" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${GH_ACCESS_TOKEN}" \
  -d '{"query": "query {viewer{login}}"}'

你应看到 HTTP/1.1 200 OK 响应及对应的响应体。

在同一个 30 秒窗口内向另一个网关实例发送相同请求。你应该会收到 HTTP/1.1 429 Too Many Requests 响应，说明这些网关实例共享同一配额。

使用 Redis 集群在网关实例之间共享配额​

你也可以使用 Redis 集群，让多个网关实例共享同一 GraphQL 限速配额。

确保你的 Redis 实例运行在集群模式（Cluster Mode）。graphql-limit-count 插件配置至少需要两个节点。

在网关组中创建一个具有以下配置的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "graphql-limit-count-route",
    "uri": "/graphql",
    "plugins": {
      "graphql-limit-count": {
        "count": 2,
        "time_window": 30,
        "rejected_code": 429,
        "key": "remote_addr",
        "policy": "redis-cluster",
        "redis_cluster_nodes": [
          "192.168.xxx.xxx:6379",
          "192.168.xxx.xxx:16379"
        ],
        "redis_password": "p@ssw0rd",
        "redis_cluster_name": "redis-cluster-1",
        "redis_cluster_ssl": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "pass_host": "node",
      "scheme": "https",
      "nodes": {
        "api.github.com:443": 1
      }
    }
  }'

❶ policy: 设置为 redis-cluster 以使用 Redis 集群进行限速。

❷ redis_cluster_nodes: 设置为 Redis 集群中的 Redis 节点地址。

❸ redis_password: 设置为 Redis 集群的密码（如果有）。

❹ redis_cluster_name: 设置为 Redis 集群名称。

❺ redis_cluster_ssl: 启用与 Redis 集群的 SSL/TLS 通信。

发送一个深度为 2 的 GraphQL 查询请求到一个网关实例：

curl -i "http://127.0.0.1:9080/graphql" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${GH_ACCESS_TOKEN}" \
  -d '{"query": "query {viewer{login}}"}'

你应看到 HTTP/1.1 200 OK 响应及对应的响应体。

在同一个 30 秒窗口内向另一个网关实例发送相同请求。你应该会收到 HTTP/1.1 429 Too Many Requests 响应，说明这些网关实例共享同一配额。

按查询复杂度限速​

以下示例展示了如何根据查询解析的节点（而不是查询深度）计算原始分数，并直接拒绝计费成本超出固定预算的查询。

使用 Ingress Controller 示例前，请先完成设置 Ingress Controller 和网关。Gateway API 示例使用 APISIX 安装中位于 aic 命名空间、名为 apisix 的 Gateway；若使用其他部署方式（包括 API7 网关），请替换为实际安装的 Gateway 名称。

创建一条配置了 graphql-limit-count 插件的路由，按 complexity 计费。它为每个远程地址在 30 秒窗口内提供 100 的配额，并拒绝单次成本超过 20 的查询：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "graphql-cost-route",
    "uri": "/graphql",
    "plugins": {
      "graphql-limit-count": {
        "count": 100,
        "time_window": 30,
        "rejected_code": 429,
        "key_type": "var",
        "key": "remote_addr",
        "policy": "local",
        "show_limit_quota_header": true,
        "cost_strategy": "complexity",
        "max_cost": 20
      }
    },
    "upstream": {
      "type": "roundrobin",
      "pass_host": "node",
      "scheme": "https",
      "nodes": {
        "api.github.com:443": 1
      }
    }
  }'

向网关实例发送一个较小的查询：

curl -i "http://127.0.0.1:9080/graphql" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${GH_ACCESS_TOKEN}" \
  -d '{"query": "query {viewer{login}}"}'

你应该会收到 HTTP/1.1 200 OK 响应，其中带有本次计费的成本：

X-Graphql-Query-Cost: 4

再发送一个计费成本超出预算的查询：

curl -i "http://127.0.0.1:9080/graphql" -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${GH_ACCESS_TOKEN}" \
  -d '{"query": "query {viewer{login name email location company bio websiteUrl twitterUsername createdAt updatedAt databaseId url avatarUrl isHireable isViewer isEmployee isSiteAdmin pronouns}}"}'

你应该会收到 HTTP/1.1 403 Forbidden 响应，且该查询从未到达上游：

{"message":"Invalid graphql request: query cost 21 exceeds max_cost 20"}