插件

本文档将介绍 APISIX 中插件（Plugins）的基本概念以及为什么需要插件。你将了解一些相关概念，包括插件启用、插件配置文件的优先级、插件执行过滤器和顺序，以及插件开发。

在文档末尾探索其他资源，以获取有关相关主题的更多信息。

概述

APISIX 插件（Plugins）扩展了 APISIX 的功能，以满足组织或用户在流量管理、可观测性、安全性、请求/响应转换、无服务器计算等方面的特定需求。

APISIX 提供了许多现有的插件，可以根据你的需求进行自定义和编排。这些插件可以全局启用以在每个传入请求上触发，或者绑定到其他对象，例如路由、服务、消费者、消费者组或插件配置。参见插件中心获取插件清单及其用法。

如果现有的 APISIX 插件不能满足你的需求，你还可以用 Lua 或其他语言（如 Java、Python、Go 和 Wasm）编写自己的插件。

插件安装

默认情况下，大多数 APISIX 插件都已安装：

apisix/cli/config.lua
local _M = {
  ...
  plugins = {
    "real-ip",
    "ai",
    "client-control",
    "proxy-control",
    "request-id",
    "zipkin",
    "ext-plugin-pre-req",
    "fault-injection",
    "mocking",
    "serverless-pre-function",
    ...
  },
  ...
}

如果你想调整插件安装，请将自定义的 plugins 配置添加到 config.yaml。例如：

plugins:
  - real-ip
  - ai
  - client-control
  - proxy-control
  - request-id
  - zipkin
  - ext-plugin-pre-req
  - fault-injection
  # - mocking                 # do not install
  - serverless-pre-function
  ...                         # other plugins

有关完整的配置参考，请参阅 config.yaml.example。

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

插件执行生命周期

安装的插件首先被初始化。然后根据定义的 JSON Schema 检查插件的配置，以确保插件配置架构正确。

当请求通过 APISIX 时，插件的相应方法将在以下一个或多个阶段执行：rewrite、access、before_proxy、header_filter、body_filter 和 log。这些阶段很大程度上受 OpenResty 指令的影响。

要了解有关自定义插件开发阶段的更多信息，请参阅插件开发操作指南。

插件执行顺序

对于匹配的 HTTP 路由，全局插件和局部插件按阶段交错执行：

rewrite 阶段的全局规则插件；
rewrite 阶段的局部绑定插件；
access 阶段的全局规则插件；
access 阶段的局部绑定插件。

因此，全局插件会在同一阶段的局部插件之前运行，但局部 rewrite 处理程序会先于所有全局 access 处理程序运行。不要假设所有全局插件都会在全部路由或服务插件之前执行完毕。

在每个全局或局部阶段组内，你可以通过 _meta.priority 定义优先级，该优先级会覆盖插件的默认优先级。同一组内优先级较高的插件先运行。优先级不会让插件跨越阶段或全局/局部边界。有关示例，请参阅插件通用配置。

如果某个插件在一个阶段中终止请求，原本应在其后运行的处理程序将被跳过，其中包括同一组中优先级较低的插件以及请求生命周期中安排在后面的阶段组。

插件合并优先级

当同一个插件在全局规则中全局配置，并在对象（例如路由）中局部配置时，两个插件实例都会按顺序执行。

如果同一个插件在多个对象上局部配置，APISIX 会合并这些配置，并只执行一个局部插件实例。合并遵循以下优先级：

Consumer > Consumer Group > Route > Plugin Config > Service

如果这些对象为同一个插件提供了不同配置，APISIX 会使用优先级最高的配置。

插件执行过滤器

默认情况下，所有插件都会由匹配已配置路由的传入请求触发。当插件只应针对满足额外条件的请求运行时，可以使用执行过滤器。

APISIX 允许通过将 _meta.filter 配置应用于插件来动态控制插件执行。该配置支持评估各种内置变量和 APISIX 表达式。

有关示例，请参阅插件通用配置。

插件开发

APISIX 支持多种语言的插件扩展，包括 Lua、Java、Python、Go 和 Wasm。插件以三种主要方式运行：

Lua 插件在 APISIX 中原生运行。
Java、Python 和 Go 插件在其相应的 APISIX 插件运行器中运行，通过远程过程调用 (RPC) 进行通信。
Wasm 插件在 APISIX Wasm 插件运行时中运行。

要了解有关开发插件的更多信息，请参阅用 Lua 创建插件。

概述​

插件安装​

插件执行生命周期​

插件执行顺序​

插件合并优先级​

插件执行过滤器​

插件开发​

其他资源​

概述