From 4b956e27b38012862d2e2e8f1ecfe1e6a7157cfb Mon Sep 17 00:00:00 2001 From: kayx23 Date: Thu, 20 Aug 2026 16:58:10 +0800 Subject: [PATCH 1/2] docs: correct global plugin execution order --- docs/en/latest/terminology/global-rule.md | 2 +- docs/en/latest/terminology/plugin.md | 15 +++++++-------- docs/zh/latest/terminology/global-rule.md | 2 +- docs/zh/latest/terminology/plugin.md | 15 +++++++-------- 4 files changed, 16 insertions(+), 18 deletions(-) diff --git a/docs/en/latest/terminology/global-rule.md b/docs/en/latest/terminology/global-rule.md index 1007f4b05ad2..96d53c41036c 100644 --- a/docs/en/latest/terminology/global-rule.md +++ b/docs/en/latest/terminology/global-rule.md @@ -30,7 +30,7 @@ description: This article describes how to use global rules. 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. +Starting with APISIX 3.17.0, a global-rule plugin runs before a locally bound plugin in the same phase. However, locally bound `rewrite` handlers run before global-rule `access` handlers. See [Plugins execution order](./plugin.md#plugins-execution-order) for the complete order and the behavior in earlier versions. ## Example diff --git a/docs/en/latest/terminology/plugin.md b/docs/en/latest/terminology/plugin.md index 0aee6fc13bbe..bbffe83772e2 100644 --- a/docs/en/latest/terminology/plugin.md +++ b/docs/en/latest/terminology/plugin.md @@ -95,17 +95,16 @@ When a request goes through APISIX, the plugin's corresponding methods are execu ## Plugins execution order -In general, plugins are executed in the following order: +Starting with APISIX 3.17.0, global and locally bound plugins for a matched HTTP Route are interleaved by phase: -1. Plugins in [global rules](./global-rule.md) - 1. plugins in rewrite phase - 2. plugins in access phase +1. global-rule plugins in the `rewrite` phase; +2. locally bound plugins in the `rewrite` phase; +3. global-rule plugins in the `access` phase; and +4. locally bound plugins in the `access` phase. -2. Plugins bound to other objects - 1. plugins in rewrite phase - 2. plugins in access phase +In APISIX 3.16.0 and earlier, both global-rule phases ran before the locally bound plugin phases. With the current order, a locally bound `rewrite` handler runs before every global-rule `access` handler. If a `rewrite` handler terminates the request, the `access` handlers scheduled after it do not run, but `log` handlers still run. -Within each phase, you can optionally define a new priority number in the `_meta.priority` field of the plugin, which takes precedence over the default plugins priority during execution. Plugins with higher priority numbers are executed first. +Within each of these groups, you can optionally define a new priority number in the `_meta.priority` field of the plugin, which takes precedence over the default plugin priority during execution. Plugins with higher priority numbers are executed first. A priority does not move a plugin across phase or global/local groups. For example, if you want to have `limit-count` (priority 1002) run before `ip-restriction` (priority 3000) when requests hit a route, you can do so by passing a higher priority number to `_meta.priority` field of `limit-count`: diff --git a/docs/zh/latest/terminology/global-rule.md b/docs/zh/latest/terminology/global-rule.md index 8b3dc7ad4866..f5d859385a4b 100644 --- a/docs/zh/latest/terminology/global-rule.md +++ b/docs/zh/latest/terminology/global-rule.md @@ -33,7 +33,7 @@ description: 本文介绍了全局规则的概念以及如何启用全局规则 如果你需要一个能作用于所有请求的 Plugin，可以通过 Global Rules 启用一个全局的插件配置。 -全局规则相对于 Route、Service、Plugin Config、Consumer 中的插件配置，Global Rules 中的插件总是优先执行。 +自 APISIX 3.17.0 起，同一阶段内的全局规则插件会先于局部绑定的插件执行。但是，局部绑定插件的 `rewrite` 处理函数会先于全局规则插件的 `access` 处理函数执行。完整顺序以及早期版本的行为请参见[插件执行顺序](./plugin.md#插件执行顺序)。 ## 使用示例 diff --git a/docs/zh/latest/terminology/plugin.md b/docs/zh/latest/terminology/plugin.md index 263998ff9510..02836d4700d5 100644 --- a/docs/zh/latest/terminology/plugin.md +++ b/docs/zh/latest/terminology/plugin.md @@ -94,17 +94,16 @@ plugins: ## 插件执行顺序 -通常情况下，插件按照以下顺序执行： +自 APISIX 3.17.0 起，对于匹配 HTTP Route 的请求，全局规则插件和局部绑定的插件会按阶段交错执行： -1. [全局规则](./global-rule.md) 插件 - 1. rewrite 阶段的插件 - 2. access 阶段的插件 +1. 全局规则插件的 `rewrite` 阶段； +2. 局部绑定插件的 `rewrite` 阶段； +3. 全局规则插件的 `access` 阶段； +4. 局部绑定插件的 `access` 阶段。 -2. 绑定到其他对象的插件 - 1. rewrite 阶段的插件 - 2. access 阶段的插件 +在 APISIX 3.16.0 及更早版本中，全局规则插件的两个阶段都先于局部绑定插件的阶段执行。按照当前顺序，局部绑定插件的 `rewrite` 处理函数会先于所有全局规则插件的 `access` 处理函数执行。如果某个 `rewrite` 处理函数终止了请求，则排在它之后的 `access` 处理函数不会执行，但 `log` 处理函数仍会执行。 -在每个阶段内，你可以在插件的 `_meta.priority` 字段中可选地定义一个新的优先级数，该优先级数优先于默认插件优先级在执行期间。具有更高优先级数的插件首先执行。 +在上述每个分组内，你可以在插件的 `_meta.priority` 字段中定义新的优先级数，该优先级会在执行时覆盖插件的默认优先级。优先级数越高，插件越先执行。优先级不会使插件跨越阶段或全局、局部分组执行。 例如，如果你想在请求到达路由时，让 `limit-count`（优先级 1002）先于 `ip-restriction`（优先级 3000）运行，可以通过将更高的优先级数传递给 `limit-count` 的 `_meta.priority` 字段来实现： From 6cc23d5e89d360363cbbfa5a288a5c5ab924b2b6 Mon Sep 17 00:00:00 2001 From: kayx23 Date: Thu, 20 Aug 2026 17:11:01 +0800 Subject: [PATCH 2/2] docs: remove version-specific execution wording --- docs/en/latest/terminology/global-rule.md | 2 +- docs/en/latest/terminology/plugin.md | 4 ++-- docs/zh/latest/terminology/global-rule.md | 2 +- docs/zh/latest/terminology/plugin.md | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/en/latest/terminology/global-rule.md b/docs/en/latest/terminology/global-rule.md index 96d53c41036c..a42403fdf5be 100644 --- a/docs/en/latest/terminology/global-rule.md +++ b/docs/en/latest/terminology/global-rule.md @@ -30,7 +30,7 @@ description: This article describes how to use global rules. 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. -Starting with APISIX 3.17.0, a global-rule plugin runs before a locally bound plugin in the same phase. However, locally bound `rewrite` handlers run before global-rule `access` handlers. See [Plugins execution order](./plugin.md#plugins-execution-order) for the complete order and the behavior in earlier versions. +A global-rule plugin runs before a locally bound plugin in the same phase. However, locally bound `rewrite` handlers run before global-rule `access` handlers. See [Plugins execution order](./plugin.md#plugins-execution-order) for the complete order. ## Example diff --git a/docs/en/latest/terminology/plugin.md b/docs/en/latest/terminology/plugin.md index bbffe83772e2..f3d35a11794f 100644 --- a/docs/en/latest/terminology/plugin.md +++ b/docs/en/latest/terminology/plugin.md @@ -95,14 +95,14 @@ When a request goes through APISIX, the plugin's corresponding methods are execu ## Plugins execution order -Starting with APISIX 3.17.0, global and locally bound plugins for a matched HTTP Route are interleaved by phase: +Global and locally bound plugins for a matched HTTP Route are interleaved by phase: 1. global-rule plugins in the `rewrite` phase; 2. locally bound plugins in the `rewrite` phase; 3. global-rule plugins in the `access` phase; and 4. locally bound plugins in the `access` phase. -In APISIX 3.16.0 and earlier, both global-rule phases ran before the locally bound plugin phases. With the current order, a locally bound `rewrite` handler runs before every global-rule `access` handler. If a `rewrite` handler terminates the request, the `access` handlers scheduled after it do not run, but `log` handlers still run. +A locally bound `rewrite` handler runs before every global-rule `access` handler. If a `rewrite` handler terminates the request, the `access` handlers scheduled after it do not run, but `log` handlers still run. Within each of these groups, you can optionally define a new priority number in the `_meta.priority` field of the plugin, which takes precedence over the default plugin priority during execution. Plugins with higher priority numbers are executed first. A priority does not move a plugin across phase or global/local groups. diff --git a/docs/zh/latest/terminology/global-rule.md b/docs/zh/latest/terminology/global-rule.md index f5d859385a4b..b2df11d54f35 100644 --- a/docs/zh/latest/terminology/global-rule.md +++ b/docs/zh/latest/terminology/global-rule.md @@ -33,7 +33,7 @@ description: 本文介绍了全局规则的概念以及如何启用全局规则 如果你需要一个能作用于所有请求的 Plugin，可以通过 Global Rules 启用一个全局的插件配置。 -自 APISIX 3.17.0 起，同一阶段内的全局规则插件会先于局部绑定的插件执行。但是，局部绑定插件的 `rewrite` 处理函数会先于全局规则插件的 `access` 处理函数执行。完整顺序以及早期版本的行为请参见[插件执行顺序](./plugin.md#插件执行顺序)。 +同一阶段内的全局规则插件会先于局部绑定的插件执行。但是，局部绑定插件的 `rewrite` 处理函数会先于全局规则插件的 `access` 处理函数执行。完整顺序请参见[插件执行顺序](./plugin.md#插件执行顺序)。 ## 使用示例 diff --git a/docs/zh/latest/terminology/plugin.md b/docs/zh/latest/terminology/plugin.md index 02836d4700d5..5656c9fc6107 100644 --- a/docs/zh/latest/terminology/plugin.md +++ b/docs/zh/latest/terminology/plugin.md @@ -94,14 +94,14 @@ plugins: ## 插件执行顺序 -自 APISIX 3.17.0 起，对于匹配 HTTP Route 的请求，全局规则插件和局部绑定的插件会按阶段交错执行： +对于匹配 HTTP Route 的请求，全局规则插件和局部绑定的插件会按阶段交错执行： 1. 全局规则插件的 `rewrite` 阶段； 2. 局部绑定插件的 `rewrite` 阶段； 3. 全局规则插件的 `access` 阶段； 4. 局部绑定插件的 `access` 阶段。 -在 APISIX 3.16.0 及更早版本中，全局规则插件的两个阶段都先于局部绑定插件的阶段执行。按照当前顺序，局部绑定插件的 `rewrite` 处理函数会先于所有全局规则插件的 `access` 处理函数执行。如果某个 `rewrite` 处理函数终止了请求，则排在它之后的 `access` 处理函数不会执行，但 `log` 处理函数仍会执行。 +局部绑定插件的 `rewrite` 处理函数会先于所有全局规则插件的 `access` 处理函数执行。如果某个 `rewrite` 处理函数终止了请求，则排在它之后的 `access` 处理函数不会执行，但 `log` 处理函数仍会执行。 在上述每个分组内，你可以在插件的 `_meta.priority` 字段中定义新的优先级数，该优先级会在执行时覆盖插件的默认优先级。优先级数越高，插件越先执行。优先级不会使插件跨越阶段或全局、局部分组执行。