跳到主要内容
版本:3.2.16.3

插件

在本文档中,你将了解 API7 企业版中插件的基本概念以及为什么需要插件。你将了解一些插件的相关概念,包括插件启用、插件配置文件优先级、插件执行过滤器和顺序,以及插件开发。

概述

API7 企业版插件扩展了 API7 企业版的功能,满足组织或用户在流量管理、可观测性、安全性、请求/响应转换、无服务器计算等方面的特定要求。

API7 企业版提供了许多插件,可以根据你的需求进行定制和编排。这些插件可以全局启用,以便在每个传入请求上触发,或者本地绑定到其他对象,例如路由服务消费者

如果现有的 API7 企业版插件不能满足你的需求,你还可以使用 Lua 或 Java、Python、Go、Wasm 等其他语言编写自己的插件。

插件执行生命周期

然后根据定义的 JSON 架构检查插件的配置,以确保插件配置架构正确。

当发送请求到 API7 企业版时,会在以下一个或多个阶段执行插件相应的方法:rewriteaccessbefore_proxyheader_filterbody_filterlog。这些阶段很大程度上受到 OpenResty 指令的影响。


路由图

想要了解有关自定义插件开发阶段的更多信息,请参阅插件开发操作指南(即将推出)。

插件执行顺序

一般来说,插件按以下顺序执行:

  1. 全局规则中的插件

    1. 重写阶段的插件
    2. 接入阶段的插件
  2. 与其他对象绑定的插件

    1. 重写阶段的插件
    2. 接入阶段的插件

在每个阶段中,你可以选择在插件的 _meta.priority 属性中定义一个新的优先级值,该值在执行期间优先于默认的插件优先级。具有较高优先级值的插件将首先执行。有关示例,请参阅插件通用配置。

插件合并优先级

当同一个插件在全局规则中全局配置和在对象(例如路由)中本地配置时,两个插件实例都会按顺序执行。

但是,如果在多个对象上本地配置同一个插件,例如在路由服务消费者上配置同一个插件,则只有一份配置副本可用。这是因为在执行期间,这些对象中配置的插件会按照特定的优先顺序进行合并:

消费者 > 路由 > 服务

因此,如果一个插件在不同对象中有不同的配置,则在合并时将使用优先级最高的插件配置。

插件执行过滤器

默认情况下,所有插件均由与路由中配置的规则匹配的传入请求触发。有时你可能需要更精细地控制插件的执行,即有条件地确定请求触发哪些插件。

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

插件全局规则

全局规则对象用来启用每个传入请求上的插件。在其他插件本地绑定到路由服务消费者等其他对象之前,就会执行全局规则。某些插件(例如 rate limitingobservability 插件)经常在全局范围内启用,为 API 提供一致且全面的保护。

插件元数据

插件元数据对象用于配置共享相同插件名称的所有插件实例的公共元数据字段。它适用于跨多个对象启用插件并且需要对其元数据字段进行通用更新。插件元数据对象只能用于具有元数据字段的部分插件,大部分插件并没有元数据的设置。

下图说明了插件元数据的概念:


具有两条路由和一个插件元数据的插件元数据图

插件元数据对象上的 log_format 将相同的日志格式统一应用于两个 syslog 插件。

如果在插件元数据和另一个对象中都定义了插件字段,则对象上的定义优先于插件元数据中的定义。