跳到主要内容
版本:3.8.x

内置变量

API7 企业版中的内置变量是预定义的变量,可直接在配置中引用。它们常用于插件配置、路由匹配和日志定制。

API7 企业版支持两种类型的内置变量:

  • NGINX 变量
  • APISIX 变量

这些变量会按照变量解析顺序进行解析。

NGINX 变量​

NGINX 提供了一组变量,可用于访问各种请求特定的信息。

一些常用的变量包括:

  • upstream_addr
  • remote_addr
  • request_uri
  • server_name
  • uri
  • http_user_agent

更多信息,请参阅NGINX 变量完整列表。

APISIX 变量​

除了 NGINX 变量,APISIX 还提供了多种内置变量:

变量名称描述
post_arg_*当内容类型为 application/x-www-form-urlencoded 时的 HTTP POST 表单数据。星号需替换为实际的 POST 表单数据名称。
post_arg.*当内容类型为 application/json、application/x-www-form-urlencoded 或 multipart/form-data 时的 HTTP POST 请求体参数。星号需替换为实际的 POST 参数名称。支持类似 JSON 路径的选择,例如 post_arg.model.version 和 post_arg.messages[*].content[*].type。
arg_*URL 查询字符串。星号需替换为实际的查询参数名称。
http_*HTTP 请求头。星号需替换为实际的请求头名称。
cookie_*请求 Cookie。星号需替换为实际的 Cookie 名称。
balancer_ip上游服务器 IP。
balancer_port上游服务器端口。
consumer_name消费者用户名。
consumer_group_id消费者组 ID。
graphql_nameGraphQL 操作名称。
graphql_operationGraphQL 操作类型。
graphql_root_fieldsGraphQL 根字段。
route_id路由 ID。
route_name路由名称。
service_id服务 ID。
service_name服务名称。
resp_bodyHTTP 响应体。
mqtt_client_idMQTT 协议中的客户端 ID。
redis_cmd_lineRedis 命令。
rpc_timeRPC 请求往返时间。
external_user.*外部用户信息(自 API7 Enterprise 3.8.19 起可用)。该变量由 openid-connect 插件和开发者 OAuth 凭据注入,可供其他插件使用。例如,将 key 设置为 ${external_user.preferred_username} 时,limit-count-advanced 可以按用户名进行限流。

变量解析顺序​

API7 企业版按以下顺序解析变量:

  1. APISIX 变量
  2. NGINX 变量

如果某个变量已在自定义变量中成功获取,API7 企业版将不再继续查找 APISIX 或 NGINX 中的同名变量。

换句话说,自定义变量会覆盖 APISIX 或 NGINX 中的同名变量,以确保更贴合您的实际业务需求。

变量语法​

有效的变量名可以包含字母、下划线(_)和句点(.)。

使用反斜杠(\)转义的变量不会被当作变量,例如 \$variable_name。

简单形式与大括号形式​

变量可以使用两种形式引用:

  • $variable_name
  • ${variable_name}

两种语法都受支持,但在某些上下文中必须使用大括号形式,以确保正确解析。

如果后面的字符不能作为变量名的一部分,无括号的 $variable 形式有效。例如,以下形式等价:

  • $http_host 和 ${http_host}
  • $arg_username-$arg_userid 和 ${arg_username}-${arg_userid}

当变量后面跟着可能属于变量名的字符(例如字母)时,解析器会将其错误地解释为更长的变量名。例如,对于 https://$http_baseurl.com,解析器会把整个字符串 http_baseurl.com 作为变量,这是不正确的。在这种情况下,应使用大括号形式 https://${http_baseurl}.com 明确界定变量。

使用 ?? 运算符时也需要大括号形式。

使用 ?? 设置默认值​

你可以使用 ?? 运算符为变量指定默认值。如果变量未定义或没有值,将使用运算符后面的值。

示例行为
${http_username ?? anonymous}如果 HTTP 请求头 username 有值,则使用该值,否则使用字符串 anonymous。
${http_count ?? 10}如果 HTTP 请求头 count 有值,则使用该值,否则使用数字 10。