This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 54215077d docs: update global-rule/plugin-config/plugin/ docs (#8262)
54215077d is described below
commit 54215077d6a0eac80d089ae0754b8d5698bc3548
Author: Fei Han <[email protected]>
AuthorDate: Mon Nov 28 17:23:49 2022 +0800
docs: update global-rule/plugin-config/plugin/ docs (#8262)
Co-authored-by: Sylvia <[email protected]>
---
docs/en/latest/terminology/global-rule.md | 9 +-
docs/en/latest/terminology/plugin-config.md | 79 +++++----
docs/en/latest/terminology/plugin.md | 25 ++-
docs/zh/latest/terminology/global-rule.md | 30 +++-
docs/zh/latest/terminology/plugin-config.md | 225 +++++++++++------------
docs/zh/latest/terminology/plugin.md | 265 +++++++++++++++-------------
6 files changed, 357 insertions(+), 276 deletions(-)
diff --git a/docs/en/latest/terminology/global-rule.md
b/docs/en/latest/terminology/global-rule.md
index 67b3b2db0..efb45885f 100644
--- a/docs/en/latest/terminology/global-rule.md
+++ b/docs/en/latest/terminology/global-rule.md
@@ -1,5 +1,10 @@
---
-title: Global Rule
+title: Global Rules
+keywords:
+ - API gateway
+ - Apache APISIX
+ - Global Rules
+description: This article describes how to use global rules.
---
<!--
@@ -25,6 +30,8 @@ title: Global Rule
A [Plugin](./plugin.md) configuration can be bound directly to a
[Route](./route.md), a [Service](./service.md) or a [Consumer](./consumer.md).
But what if we want a Plugin to work on all requests? This is where we register
a global Plugin with Global Rule.
+Compared with the plugin configuration in Route, Service, Plugin Config, and
Consumer, the plugin in the Global Rules is always executed first.
+
## Example
The example below shows how you can use the `limit-count` Plugin on all
requests:
diff --git a/docs/en/latest/terminology/plugin-config.md
b/docs/en/latest/terminology/plugin-config.md
index ce73ce172..3c1ec9d1d 100644
--- a/docs/en/latest/terminology/plugin-config.md
+++ b/docs/en/latest/terminology/plugin-config.md
@@ -26,45 +26,60 @@ description: Plugin Config in Apache APISIX.
#
-->
+## Description
+
Plugin Configs are used to extract commonly used [Plugin](./plugin.md)
configurations and can be bound directly to a [Route](./route.md).
+While configuring the same plugin, only one copy of the configuration is
valid. The order of precedence is always `Consumer` > `Consumer Group` >
`Route` > `plugin_config` > `Service`.
+
+## Example
+
The example below illustrates how to create a Plugin Config and bind it to a
Route:
-```shell
-curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "desc": "blah",
- "plugins": {
- "limit-count": {
- "count": 2,
- "time_window": 60,
- "rejected_code": 503
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+ {
+ "desc": "blah",
+ "plugins": {
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503
+ }
}
- }
-}'
-```
+ }'
+ ```
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "uris": ["/index.html"],
- "plugin_config_id": 1,
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+ {
+ "uris": ["/index.html"],
+ "plugin_config_id": 1,
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
}
- }
-}'
-```
+ }'
+ ```
-When APISIX can't find the Plugin Config with the `id`, the requests reaching
this Route are terminated with a status code of 503.
+When APISIX can't find the Plugin Config with the `id`, the requests reaching
this Route are terminated with a status code of `503`.
-If a Route already has the `plugins` field configured, the plugins in the
Plugin Config will effectively be merged to it. The same plugin in the Plugin
Config will not override the ones configured directly in the Route.
+:::note
-For example, if we configure a Plugin Config as shown below
+If a Route already has the `plugins` field configured, the plugins in the
Plugin Config will effectively be merged to it.
-```
+The same plugin in the Plugin Config will not override the ones configured
directly in the Route. For more information, see [Plugin](./plugin.md).
+
+:::
+
+For example, if you configure a Plugin Config as shown below:
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
"desc": "I am plugin_config 1",
"plugins": {
@@ -85,7 +100,9 @@ For example, if we configure a Plugin Config as shown below
to a Route as shown below,
-```
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
"uris": ["/index.html"],
"plugin_config_id": 1,
@@ -112,7 +129,9 @@ to a Route as shown below,
the effective configuration will be as the one shown below:
-```
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
"uris": ["/index.html"],
"upstream": {
diff --git a/docs/en/latest/terminology/plugin.md
b/docs/en/latest/terminology/plugin.md
index 53227904a..13e496454 100644
--- a/docs/en/latest/terminology/plugin.md
+++ b/docs/en/latest/terminology/plugin.md
@@ -1,5 +1,12 @@
---
title: Plugin
+keywords:
+ - API Gateway
+ - Apache APISIX
+ - Plugin
+ - Filter
+ - Priority
+description: This article introduces the related information of the APISIX
Plugin object and how to use it, and introduces how to customize the plugin
priority, customize the error response, and dynamically control the execution
status of the plugin.
---
<!--
@@ -25,13 +32,15 @@ title: Plugin
This represents the configuration of the plugins that are executed during the
HTTP request/response lifecycle. A **Plugin** configuration can be bound
directly to a [`Route`](./route.md), a [`Service`](./service.md), a
[`Consumer`](./consumer.md) or a [`Plugin Config`](./plugin-config.md).
+You can also refer to [Admin API](../admin-api.md#plugin) for how to use this
resource.
+
:::note
While configuring the same plugin, only one copy of the configuration is
valid. The order of precedence is always `Consumer` > `Consumer Group` >
`Route` > `plugin_config` > `Service`.
:::
-While [configuring
APISIX](./architecture-design/apisix.md#configuring-apisix), you can declare
the Plugins that are supported by the local APISIX node. This acts as a
whitelisting mechanism as Plugins that are not in this whitelist will be
automatically ignored. So, this feature can be used to temporarily turn
off/turn on specific plugins.
+While configuring APISIX, you can declare the Plugins that are supported by
the local APISIX node. This acts as a whitelisting mechanism as Plugins that
are not in this whitelist will be automatically ignored. So, this feature can
be used to temporarily turn off/turn on specific plugins.
## Adding a Plugin
@@ -78,12 +87,12 @@ ip-restriction exits with http status code 403
Some common configurations can be applied to plugins through the `_meta`
configuration items, the specific configuration items are as follows:
-| Name | Type | Description |
-|--------------|------|-------------|
-| disable | boolean | Whether to disable the plugin |
-| error_response | string/object | Custom error response |
-| priority | integer | Custom plugin priority |
-| filter | array | Depending on the requested parameters, it is decided at
runtime whether the plugin should be executed. Something like this: `{{var,
operator, val}, {var, operator, val}, ...}}`. For example: `{"arg_version",
"==", "v2"}`, indicating that the current request parameter `version` is `v2`.
The variables here are consistent with NGINX internal variables. For details on
supported operators, please see
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list). |
+| Name | Type | Description |
+|----------------|--------------- |-------------|
+| disable | boolean | When set to `true`, the plugin is
disabled. |
+| error_response | string/object | Custom error response. |
+| priority | integer | Custom plugin priority. |
+| filter | array | Depending on the requested parameters, it
is decided at runtime whether the plugin should be executed. Something like
this: `{{var, operator, val}, {var, operator, val}, ...}}`. For example:
`{"arg_version", "==", "v2"}`, indicating that the current request parameter
`version` is `v2`. The variables here are consistent with NGINX internal
variables. For details on supported operators, please see
[lua-resty-expr](https://github.com/api7/lua-resty-expr#o [...]
### Disable the plugin
@@ -103,7 +112,7 @@ Through the `disable` configuration, you can add a new
plugin with disabled stat
Through the `error_response` configuration, you can configure the error
response of any plugin to a fixed value to avoid troubles caused by the
built-in error response information of the plugin.
-The configuration below means to customize the error response of the
`jwt-auth` plugin to '{"message": "Missing credential in request"}'.
+The configuration below means to customize the error response of the
`jwt-auth` plugin to `Missing credential in request`.
```json
{
diff --git a/docs/zh/latest/terminology/global-rule.md
b/docs/zh/latest/terminology/global-rule.md
index 63183462b..a8080ff28 100644
--- a/docs/zh/latest/terminology/global-rule.md
+++ b/docs/zh/latest/terminology/global-rule.md
@@ -1,5 +1,11 @@
---
-title: Global rule
+title: Global rules
+keywords:
+ - API 网关
+ - Apache APISIX
+ - Global Rules
+ - 全局规则
+description: 本文介绍了全局规则的概念以及如何启用全局规则。
---
<!--
@@ -21,12 +27,20 @@ title: Global rule
#
-->
-[Plugin](plugin.md) 配置可直接绑定在 [Route](route.md) 上，也可以被绑定在 [Service](service.md)
或 [Consumer](consumer.md) 上，如果我们需要一个能作用于所有请求的 [Plugin](plugin.md) 该怎么办呢？
-这时候我们可以使用 `GlobalRule` 来注册一个全局的 [Plugin](plugin.md):
+## 描述
+
+[Plugin](plugin.md) 配置可直接绑定在 [Route](route.md) 上，也可以被绑定在 [Service](service.md)
或 [Consumer](consumer.md) 上。
+
+如果你需要一个能作用于所有请求的 Plugin，可以通过 Global Rules 启用一个全局的插件配置。
+
+全局规则相对于 Route、Service、Plugin Config、Consumer 中的插件配置，Global Rules 中的插件总是优先执行。
+
+## 使用示例
+
+以下示例展示了如何为所有请求启用 `limit-count` 插件：
```shell
-curl -X PUT \
- https://{apisix_listen_address}/apisix/admin/global_rules/1 \
+curl https://127.0.0.1:9180/apisix/admin/global_rules/1 -X PUT \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
-d '{
@@ -42,10 +56,8 @@ curl -X PUT \
}'
```
-如上所注册的 `limit-count` 插件将会作用于所有的请求。
-
-我们可以通过以下接口查看所有的 `GlobalRule`:
+你也可以通过以下命令查看所有的全局规则：
```shell
-curl https://{apisix_listen_address}/apisix/admin/global_rules -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1'
+curl https://127.0.0.1:9180/apisix/admin/global_rules -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1'
```
diff --git a/docs/zh/latest/terminology/plugin-config.md
b/docs/zh/latest/terminology/plugin-config.md
index e7132c635..7603ee716 100644
--- a/docs/zh/latest/terminology/plugin-config.md
+++ b/docs/zh/latest/terminology/plugin-config.md
@@ -29,135 +29,140 @@ description: Plugin Config 对象，可以用于创建一组通用的插件配
## 描述
-在很多情况下，我们在不同的路由中会使用相同的插件规则，此时就可以通过 `Plugin Config` 来设置这些规则。`plugins` 的配置可以通过
Admin API `/apisix/admin/plugin_configs` 进行单独配置，在路由中使用`plugin_config_id`
与之进行关联。插件配置属于一组通用插件配置的抽象。
+在很多情况下，我们在不同的路由中会使用相同的插件规则，此时就可以通过 Plugin Config 来设置这些规则。Plugin Config
属于一组通用插件配置的抽象。
-## 配置步骤
+`plugins` 的配置可以通过 [Admin API](../admin-api.md#plugin-config)
`/apisix/admin/plugin_configs` 进行单独配置，在路由中使用 `plugin_config_id` 与之进行关联。
+
+对于同一个插件的配置，只能有一个是有效的，优先级为 Consumer > Route > Plugin Config > Service。
+
+## 使用示例
你可以参考如下步骤将 Plugin Config 绑定在路由上。
1. 创建 Plugin config。
-```shell
-curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "desc": "enable limit-count plugin",
- "plugins": {
- "limit-count": {
- "count": 2,
- "time_window": 60,
- "rejected_code": 503
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+ {
+ "desc": "enable limit-count plugin",
+ "plugins": {
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503
+ }
}
- }
-}'
-```
+ }'
+ ```
2. 创建路由并绑定 `Plugin Config 1`。
-```
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "uris": ["/index.html"],
- "plugin_config_id": 1,
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+ {
+ "uris": ["/index.html"],
+ "plugin_config_id": 1,
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
}
- }
-}'
-```
+ }'
+ ```
-如果找不到对应的 Plugin config，该路由上的请求会报 503 错误。
+如果找不到对应的 Plugin Config，该路由上的请求会报 `503` 错误。
## 注意事项
如果路由中已经配置了 `plugins`，那么 Plugin Config 里面的插件配置将会与 `plugins` 合并。
-相同的插件不会覆盖掉 `plugins` 原有的插件。
-
-例如：
-
-```shell
-curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 \
--H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "desc": "enable ip-restruction and limit-count plugin",
- "plugins": {
- "ip-restriction": {
- "whitelist": [
- "127.0.0.0/24",
- "113.74.26.106"
- ]
- },
- "limit-count": {
- "count": 2,
- "time_window": 60,
- "rejected_code": 503
+相同的插件不会覆盖掉 `plugins` 原有的插件配置。详细信息，请参考 [Plugin](./plugin.md)。
+
+1. 假设你创建了一个 Plugin Config。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+ {
+ "desc": "enable ip-restruction and limit-count plugin",
+ "plugins": {
+ "ip-restriction": {
+ "whitelist": [
+ "127.0.0.0/24",
+ "113.74.26.106"
+ ]
+ },
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503
+ }
}
- }
-}'
-```
-
-在路由中引入 Plugin Config：
-
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "uris": ["/index.html"],
- "plugin_config_id": 1,
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+ }'
+ ```
+
+2. 并在路由中引入 Plugin Config。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+ {
+ "uris": ["/index.html"],
+ "plugin_config_id": 1,
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
}
- }
- "plugins": {
- "proxy-rewrite": {
- "uri": "/test/add",
- "host": "apisix.iresty.com"
- },
- "limit-count": {
- "count": 20,
- "time_window": 60,
- "rejected_code": 503,
- "key": "remote_addr"
+ "plugins": {
+ "proxy-rewrite": {
+ "uri": "/test/add",
+ "host": "apisix.iresty.com"
+ },
+ "limit-count": {
+ "count": 20,
+ "time_window": 60,
+ "rejected_code": 503,
+ "key": "remote_addr"
+ }
}
- }
-}'
-```
-
-最后实现的效果如下：
-
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
--H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
-{
- "uris": ["/index.html"],
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+ }'
+ ```
+
+3. 最后实现的效果如下。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+ {
+ "uris": ["/index.html"],
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
}
- }
- "plugins": {
- "ip-restriction": {
- "whitelist": [
- "127.0.0.0/24",
- "113.74.26.106"
- ]
- },
- "proxy-rewrite": {
- "uri": "/test/add",
- "host": "apisix.iresty.com"
- },
- "limit-count": {
- "count": 20,
- "time_window": 60,
- "rejected_code": 503,
- "key": "remote_addr"
+ "plugins": {
+ "ip-restriction": {
+ "whitelist": [
+ "127.0.0.0/24",
+ "113.74.26.106"
+ ]
+ },
+ "proxy-rewrite": {
+ "uri": "/test/add",
+ "host": "apisix.iresty.com"
+ },
+ "limit-count": {
+ "count": 20,
+ "time_window": 60,
+ "rejected_code": 503,
+ "key": "remote_addr"
+ }
}
- }
-}'
-```
+ }'
+ ```
diff --git a/docs/zh/latest/terminology/plugin.md
b/docs/zh/latest/terminology/plugin.md
index b832d394c..64b24be6d 100644
--- a/docs/zh/latest/terminology/plugin.md
+++ b/docs/zh/latest/terminology/plugin.md
@@ -1,5 +1,11 @@
---
title: Plugin
+keywords:
+ - API 网关
+ - Apache APISIX
+ - 插件
+ - 插件优先级
+description: 本文介绍了 APISIX Plugin
对象的相关信息及其使用方法，并且介绍了如何自定义插件优先级、自定义错误响应、动态控制插件执行状态等。
---
<!--
@@ -21,15 +27,29 @@ title: Plugin
#
-->
-`Plugin` 表示将在 `HTTP` 请求/响应生命周期期间执行的插件配置。
+## 描述
-`Plugin` 配置可直接绑定在 `Route` 上，也可以被绑定在 `Service`、`Consumer` 或 `Plugin Config`
上。而对于同一个插件的配置，只能有一份是有效的，配置选择优先级总是 `Consumer` > `Route` > `Plugin Config` >
`Service`。
+Plugin 表示将在 HTTP 请求/响应生命周期期间执行的插件配置。Plugin 的配置信息可以直接绑定在 [Route](./route.md)
上，也可以被绑定在 [Service](./service.md)、[Consumer](./consumer.md) 或 [Plugin
Config](./plugin-config.md) 上。
-在 `conf/config.yaml` 中，可以声明本地 APISIX
节点都支持哪些插件。这是个白名单机制，不在该白名单的插件配置，都将会被自动忽略。这个特性可用于临时关闭或打开特定插件，应对突发情况非常有效。
-如果你想在现有插件的基础上新增插件，注意需要拷贝 `conf/config-default.yaml` 的插件节点内容到
`conf/config.yaml` 的插件节点中。
+你也可以参考 [Admin API](../admin-api.md#plugin) 了解如何使用该资源。
-一个插件在一次请求中只会执行一次，即使被同时绑定到多个不同对象中（比如 Route 或 Service）。
-插件运行先后顺序是根据插件自身的优先级来决定的，例如：
+:::note 注意
+
+对于同一个插件的配置，只能有一个是有效的，其插件配置优先级为 Consumer > Route > Plugin Config > Service。
+
+:::
+
+## 配置简介
+
+如果你想在现有插件的基础上新增插件，请复制 `./conf/config-default.yaml` 中的 `plugins` 参数下的插件列表到
`./conf/config.yaml` 的 `plugins` 参数中。
+
+:::tip 提示
+
+在 `./conf/config.yaml` 中的 `plugins` 参数中，可以声明本地 APISIX
节点支持了哪些插件。这是个白名单机制，不在该白名单的插件配置将被自动忽略。该特性可用于临时关闭或打开特定插件，应对突发情况非常有效。
+
+:::
+
+一个插件在一次请求中只会执行一次，即使被同时绑定到多个不同对象中（比如 Route 或
Service）。插件运行先后顺序是根据插件自身的优先级来决定的，例如：
```lua
local _M = {
@@ -41,13 +61,10 @@ local _M = {
}
```
-插件配置可存放于 Route 或 Service 中，键为 `plugins`，值是包含多个插件配置的对象。对象内部用插件名字作为 key
来保存不同插件的配置项。
-
-如下所示的配置中，包含 `limit-count` 和 `prometheus` 两种插件的配置：
+插件的配置信息，可以存放 Route、Service、Plugin Config 等对象中的 `plugins` 参数下。如下所示的配置中，包含
`limit-count` 和 `prometheus` 两个插件的配置信息：
```json
{
- ...
"plugins": {
"limit-count": {
"count": 2,
@@ -60,24 +77,30 @@ local _M = {
}
```
-并不是所有插件都有具体配置项，比如 `prometheus` 下是没有任何具体配置项，这时候用一个空的对象标识即可。
+并不是所有插件都有具体配置项，比如 `[prometheus](../plugins/prometheus.md)`
下是没有任何具体配置项，此时可以使用一个空对象启用该插件。
+
+如果一个请求因为某个插件而被拒绝，会有类似如下 `warn` 级别的日志：
-如果一个请求因为某个插件而被拒绝，会有类似这样的 warn 日志：`ip-restriction exits with http status code
403`。
+```shell
-## 插件通用配置
+ip-restriction exits with http status code 403
-通过 `_meta` 配置项可以将一些通用的配置应用于插件，具体配置项如下：
+```
-| 名称 | 类型 | 描述 |
-|--------------|------|----------------|
-| disable | boolean | 是否禁用该插件。 |
-| error_response | string/object | 自定义错误响应。 |
-| priority | integer | 自定义插件优先级。 |
-| filter | array | 根据请求的参数，在运行时控制插件是否执行。此配置由一个或多个 {var, operator, val}
元素组成列表，类似：{{var, operator, val}, {var, operator, val}, ...}}。例如
`{"arg_version", "==", "v2"}`，表示当前请求参数 `version` 是 `v2`。这里的 `var` 与 NGINX
内部自身变量命名是保持一致。操作符的具体用法请看[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list)
的 operator-list 部分。|
+## 通用配置
-### 禁用插件
+通过 `_meta` 配置项可以将一些通用的配置应用于插件，你可以参考下文使用这些通用配置。通用配置如下：
-通过 `disable` 配置，你可以新增一个处于禁用状态的插件，请求不会经过该插件。
+| 名称 | 类型 | 描述 |
+|--------------- |-------------- |----------------|
+| disable | boolean | 当设置为 `true` 时，则禁用该插件。可选值为 `true` 和 `false`。
|
+| error_response | string/object | 自定义错误响应。 |
+| priority | integer | 自定义插件优先级。 |
+| filter | array | 根据请求的参数，在运行时控制插件是否执行。此配置由一个或多个 {var,
operator, val} 元素组成列表，类似：`{{var, operator, val}, {var, operator, val},
...}}`。例如 `{"arg_version", "==", "v2"}`，表示当前请求参数 `version` 是 `v2`。这里的 `var` 与
NGINX 内部自身变量命名是保持一致。操作符的使用方法，请参考
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list)。|
+
+### 禁用指定插件
+
+通过 `disable` 参数，你可以将某个插件调整为“禁用状态”，即请求不会经过该插件。
```json
{
@@ -91,9 +114,9 @@ local _M = {
### 自定义错误响应
-通过 `error_response` 配置，可以将任意插件的错误响应配置成一个固定的值，避免因为插件内置的错误响应信息而带来困扰。
+通过 `error_response` 配置，可以将任意插件的错误响应配置成一个固定的值，避免因为插件内置的错误响应信息而带来不必要的麻烦。
-如下配置表示将 `jwt-auth` 插件的错误响应自定义为 '{"message": "Missing credential in request"}'。
+如下配置表示将 `jwt-auth` 插件的错误响应自定义为 `Missing credential in request`。
```json
{
@@ -109,7 +132,7 @@ local _M = {
### 自定义插件优先级
-所有插件都有默认优先级，但你仍可以通过 `priority` 配置项来自定义插件优先级，从而改变插件执行顺序。
+所有插件都有默认优先级，但是你仍然可以通过 `priority` 配置项来自定义插件优先级，从而改变插件执行顺序。
```json
{
@@ -134,40 +157,25 @@ local _M = {
}
```
-serverless-pre-function 的默认优先级是 10000，serverless-post-function 的默认优先级是
-2000。默认情况下会先执行 serverless-pre-function 插件，再执行 serverless-post-function 插件。
+`serverless-pre-function` 的默认优先级是 `10000`，`serverless-post-function` 的默认优先级是
`-2000`。默认情况下会先执行 `serverless-pre-function` 插件，再执行 `serverless-post-function`
插件。
-上面的配置意味着将 serverless-pre-function 插件的优先级设置为 -2000，serverless-post-function
插件的优先级设置为 10000。serverless-post-function 插件会先执行，再执行 serverless-pre-function 插件。
+上面的配置则将 `serverless-pre-function` 插件的优先级设置为 `-2000`，`serverless-post-function`
插件的优先级设置为 `10000`，因此 `serverless-post-function` 插件会优先执行。
-注意：
+:::note 注意
-- 自定义插件优先级只会影响插件实例绑定的主体，不会影响该插件的所有实例。比如上面的插件配置属于路由 A ，路由 B 上的插件
serverless-post-function 和 serverless-post-function 插件执行顺序不会受到影响，会使用默认优先级。
-- 自定义插件优先级不适用于 consumer 上配置的插件的 rewrite 阶段。路由上配置的插件的 rewrite 阶段将会优先运行，然后才会运行
consumer 上除 auth 插件之外的其他插件的 rewrite 阶段。
+- 自定义插件优先级只会影响插件实例绑定的主体，不会影响该插件的所有实例。比如上面的插件配置属于路由 A，路由 B 上的插件
`serverless-post-function` 和 `serverless-post-function` 插件执行顺序不会受到影响，会使用默认优先级。
+- 自定义插件优先级不适用于 Consumer 上配置的插件的 `rewrite` 阶段。路由上配置的插件的 `rewrite`
阶段将会优先运行，然后才会运行 Consumer 上除 `auth` 类插件之外的其他插件的 `rewrite` 阶段。
-### 动态控制插件是否执行
+:::
-默认情况下，在路由中指定的插件都会被执行。但是我们可以通过 `filter` 配置项为插件添加一个过滤器，通过过滤器的执行结果控制插件是否执行。
+### 动态控制插件执行状态
-如下配置表示，只有当请求查询参数中 `version` 值为 `v2` 时，`proxy-rewrite` 插件才会执行。
+默认情况下，在路由中指定的插件都会被执行。但是你可以通过 `filter` 配置项为插件添加一个过滤器，通过过滤器的执行结果控制插件是否执行。
-```json
-{
- "proxy-rewrite": {
- "_meta": {
- "filter": [
- ["arg_version", "==", "v2"]
- ]
- },
- "uri": "/anything"
- }
-}
-```
+1. 如下配置表示，只有当请求查询参数中 `version` 值为 `v2` 时，`proxy-rewrite` 插件才会执行。
-使用下述配置创建一条完整的路由：
-
-```json
-{
- "uri": "/get",
- "plugins": {
+ ```json
+ {
"proxy-rewrite": {
"_meta": {
"filter": [
@@ -176,85 +184,106 @@ serverless-pre-function 的默认优先级是
10000，serverless-post-function
},
"uri": "/anything"
}
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "httpbin.org:80": 1
+ }
+ ```
+
+2. 使用下述配置创建一条完整的路由。
+
+ ```json
+ {
+ "uri": "/get",
+ "plugins": {
+ "proxy-rewrite": {
+ "_meta": {
+ "filter": [
+ ["arg_version", "==", "v2"]
+ ]
+ },
+ "uri": "/anything"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "httpbin.org:80": 1
+ }
}
}
-}
-```
-
-当请求中不带任何参数时，`proxy-rewrite` 插件不会执行，请求将被转发到上游的 `/get`:
-
-```shell
-curl -v /dev/null http://127.0.0.1:9080/get -H"host:httpbin.org"
-```
-
-```shell
-< HTTP/1.1 200 OK
-......
-< Server: APISIX/2.15.0
-<
-{
- "args": {},
- "headers": {
- "Accept": "*/*",
- "Host": "httpbin.org",
- "User-Agent": "curl/7.79.1",
- "X-Amzn-Trace-Id": "Root=1-62eb6eec-46c97e8a5d95141e621e07fe",
- "X-Forwarded-Host": "httpbin.org"
- },
- "origin": "127.0.0.1, 117.152.66.200",
- "url": "http://httpbin.org/get";
-}
-```
-
-当请求中携带参数 `version=v2` 时，`proxy-rewrite` 插件执行，请求将被转发到上游的 `/anything`:
-
-```shell
-curl -v /dev/null http://127.0.0.1:9080/get?version=v2 -H"host:httpbin.org"
-```
-
-```shell
-< HTTP/1.1 200 OK
-......
-< Server: APISIX/2.15.0
-<
-{
- "args": {
- "version": "v2"
- },
- "data": "",
- "files": {},
- "form": {},
- "headers": {
- "Accept": "*/*",
- "Host": "httpbin.org",
- "User-Agent": "curl/7.79.1",
- "X-Amzn-Trace-Id": "Root=1-62eb6f02-24a613b57b6587a076ef18b4",
- "X-Forwarded-Host": "httpbin.org"
- },
- "json": null,
- "method": "GET",
- "origin": "127.0.0.1, 117.152.66.200",
- "url": "http://httpbin.org/anything?version=v2";
-}
-```
+ ```
+
+3. 当请求中不带任何参数时，`proxy-rewrite` 插件不会执行，请求将被转发到上游的 `/get`。
+
+ ```shell
+ curl -v /dev/null http://127.0.0.1:9080/get -H"host:httpbin.org"
+ ```
+
+ ```shell
+ < HTTP/1.1 200 OK
+ ......
+ < Server: APISIX/2.15.0
+ <
+ {
+ "args": {},
+ "headers": {
+ "Accept": "*/*",
+ "Host": "httpbin.org",
+ "User-Agent": "curl/7.79.1",
+ "X-Amzn-Trace-Id": "Root=1-62eb6eec-46c97e8a5d95141e621e07fe",
+ "X-Forwarded-Host": "httpbin.org"
+ },
+ "origin": "127.0.0.1, 117.152.66.200",
+ "url": "http://httpbin.org/get";
+ }
+ ```
+
+4. 当请求中携带参数 `version=v2` 时，`proxy-rewrite` 插件执行，请求将被转发到上游的 `/anything`:
+
+ ```shell
+ curl -v /dev/null http://127.0.0.1:9080/get?version=v2 -H"host:httpbin.org"
+ ```
+
+ ```shell
+ < HTTP/1.1 200 OK
+ ......
+ < Server: APISIX/2.15.0
+ <
+ {
+ "args": {
+ "version": "v2"
+ },
+ "data": "",
+ "files": {},
+ "form": {},
+ "headers": {
+ "Accept": "*/*",
+ "Host": "httpbin.org",
+ "User-Agent": "curl/7.79.1",
+ "X-Amzn-Trace-Id": "Root=1-62eb6f02-24a613b57b6587a076ef18b4",
+ "X-Forwarded-Host": "httpbin.org"
+ },
+ "json": null,
+ "method": "GET",
+ "origin": "127.0.0.1, 117.152.66.200",
+ "url": "http://httpbin.org/anything?version=v2";
+ }
+ ```
## 热加载
APISIX 的插件是热加载的，不管你是新增、删除还是修改插件，都不需要重启服务。
-只需要通过 admin API 发送一个 HTTP 请求即可：
+只需要通过 Admin API 发送一个 HTTP 请求即可：
```shell
curl http://127.0.0.1:9180/apisix/admin/plugins/reload -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT
```
-注意：如果你已经在路由规则里配置了某个插件（比如在 `route` 的 `plugins`
字段里面添加了它），然后禁用了该插件，在执行路由规则的时候会跳过这个插件。
+:::note 注意
+
+如果你已经在路由规则里配置了某个插件（比如在 Route 的 `plugins`
字段里面添加了它），然后在配置文件中禁用了该插件，在执行路由规则时则会跳过该插件。
+
+:::
## stand-alone 模式下的热加载
-参考 [stand alone 模式](../stand-alone.md) 文档里关于配置插件的内容。
+关于 Stand Alone 模式下的热加载的信息，请参考 [stand alone 模式](../stand-alone.md)。
