版本：3.19.0

插件通用配置

插件通用配置是一组可以通过 _meta 属性普遍应用于所有 APISIX 插件的配置选项。它们可用于配置：

插件条件执行
插件执行优先级
插件禁用
插件错误响应
在每个插件阶段之前执行自定义代码

`_meta.filter`

你可以使用 _meta.filter 根据请求参数配置插件的条件执行。条件是使用 APISIX 表达式创建的，并配置为数组。插件仅在满足所有条件时执行。

例如，以下配置在请求的 URI 查询参数上设置条件。只有 URI 查询参数 version 为 v2 的请求才会触发 proxy-rewrite 插件的执行，该插件在将请求转发到上游之前将请求的 URI 路径重写为 /api/v2：

{
  ...,
  "plugins": {
    "proxy-rewrite": {
      "uri": "/api/v2",
      "_meta": {
        "filter": [
          ["arg_version", "==", "v2"]
        ]
      }
    }
  }
}

不满足条件的请求将不会重写其 URI 路径，并将按原样转发。

`_meta.priority`

你可以使用 _meta.priority 来调整同一类型插件（即全局或非全局）在给定阶段内的执行顺序。一旦定义，该值将优先于配置文件中定义的默认插件优先级。

假设两个在同一阶段运行的插件 limit-count 和 ip-restriction 配置在同一路由上。limit-count 的默认优先级为 1002，ip-restriction 的默认优先级为 3000。当请求发送到路由时，ip-restriction 首先执行，因为它具有更高的默认优先级值。但是，你可以通过为 limit-count 的 _meta.priority 分配高于 3000 的优先级值（例如 3010）来在 ip-restriction 之前运行 limit-count：

{
  ...,
  "plugins": {
    "limit-count": {
      ...,
      "_meta": {
        "priority": 3010
      }
    }
  }
}

要了解更多关于全局和非全局插件一起使用时的执行顺序，请参阅插件执行顺序。

`_meta.disable`

你可以使用 _meta.disable 禁用插件，而无需从其绑定的对象中完全删除插件。

例如，你可以使用以下配置禁用 proxy-rewrite 插件：

{
  "plugins": {
    "proxy-rewrite": {
      "_meta": {
        "disable": true
      }
    }
  }
}

`_meta.error_response`

你可以使用 _meta.error_response 将插件返回的错误响应替换为固定值。当默认响应不适用时，这可以简化客户端处理逻辑。

例如，你可以自定义 limit-count 插件的错误响应：

{
  "plugins": {
    "limit-count": {
      "count": 1,
      "time_window": 60,
      "_meta": {
        "error_response": {
          "message": "You have exceeded the rate limiting threshold."
        }
      }
    }
  }
}

如果在 60 秒窗口内向插件绑定的路由发送多个请求，你应该看到以下响应：

{"message":"You have exceeded the rate limiting threshold."}

`_meta.pre_function`

你可以使用 _meta.pre_function，在每个执行阶段中，先运行自定义代码，再执行该插件。

以下示例演示如何在 proxy-rewrite 中配置 _meta.pre_function，将请求路径的 user_id 参数注册为变量，并在重写后的路径中使用该变量。

要使用路由 URI 参数，请在配置文件中将路由器设置为 radixtree_uri_with_parameter：

config.yaml
apisix:
  router:
    http: radixtree_uri_with_parameter

然后重新加载 APISIX 以使更改生效。

创建一个到 httpbin 服务的路由以检查重写后的路径：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
  "id": "pre-func-route",
  "uri": "/anything/:user_id/hello",
  "plugins": {
    "proxy-rewrite": {
      "_meta": {
        "pre_function": "return function(conf, ctx) local core = require \"apisix.core\" core.ctx.register_var(\"user_id\", function(ctx) return ctx.curr_req_matched.user_id end) end"
      },
      "uri": "/anything/$user_id/world"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

❶ 匹配请求 /anything/:user_id/hello，其中 user_id 是一个参数。

❷ 自定义 _meta.pre_function 以从请求路径中提取 user_id 值并将其保存到同名变量中。

❸ 将请求路径重写为 /anything/$user_id/world，其中 $user_id 将被替换为变量值。

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything/johndoe/hello"

响应应包含使用 user_id 值重写后的 URL：

{
  "url": "http://127.0.0.1/anything/johndoe/world"
}

与插件元数据区分

在使用插件时，了解本文档中概述的 _meta 通用配置与插件元数据之间的区别非常重要。这两个概念服务于不同的目的，不应混淆。

虽然 _meta 通用配置指的是可用于所有 APISIX 插件的配置选项，但插件元数据仅适用于具有元数据属性的插件。这些元数据属性也可以使用 Admin API 插件元数据资源进行配置。

有关更多信息，请参阅插件元数据。

_meta.filter​

_meta.priority​

_meta.disable​

_meta.error_response​

_meta.pre_function​

与插件元数据区分​