Plugin

你也可以参考 Admin API 了解如何使用该资源。

注意

对于同一个插件的配置，只能有一个是有效的，其插件配置优先级为 Consumer > Route > Plugin Config > Service。

如果你想在现有插件的基础上新增插件，请复制 中的 plugins 参数下的插件列表到 ./conf/config.yaml 的 plugins 参数中。

Plugin - 图2提示

在 ./conf/config.yaml 中的 plugins 参数中，可以声明本地 APISIX 节点支持了哪些插件。这是个白名单机制，不在该白名单的插件配置将被自动忽略。该特性可用于临时关闭或打开特定插件，应对突发情况非常有效。

一个插件在一次请求中只会执行一次，即使被同时绑定到多个不同对象中（比如 Route 或 Service）。插件运行先后顺序是根据插件自身的优先级来决定的，例如：

插件的配置信息，可以存放 Route、Service、Plugin Config 等对象中的 plugins 参数下。如下所示的配置中，包含 limit-count 和 prometheus 两个插件的配置信息：

  1. {
  2.     "plugins": {
  3.         "limit-count": {
  4.             "count": 2,
  5.             "time_window": 60,
  6.             "rejected_code": 503,
  7.             "key": "remote_addr"
  8.         },
  9.         "prometheus": {}
  10.     }
  11. }

并不是所有插件都有具体配置项，比如 prometheus 下是没有任何具体配置项，此时可以使用一个空对象启用该插件。

  2. ip-restriction exits with http status code 403

通过 _meta 配置项可以将一些通用的配置应用于插件，你可以参考下文使用这些通用配置。通用配置如下：

通过 disable 参数，你可以将某个插件调整为“禁用状态”，即请求不会经过该插件。

  1. {
  2.     "proxy-rewrite": {
  3.         "_meta": {
  4.             "disable": true
  5.         }
  6.     }
  7. }

通过 error_response 配置，可以将任意插件的错误响应配置成一个固定的值，避免因为插件内置的错误响应信息而带来不必要的麻烦。

如下配置表示将 jwt-auth 插件的错误响应自定义为 Missing credential in request。

所有插件都有默认优先级，但是你仍然可以通过 priority 配置项来自定义插件优先级，从而改变插件执行顺序。

  1.  {
  2.     "serverless-post-function": {
  3.         "_meta": {
  4.             "priority": 10000
  5.         },
  6.         "phase": "rewrite",
  7.         "functions" : ["return function(conf, ctx)
  8.                     ngx.say(\"serverless-post-function\");
  9.                     end"]
  10.     "serverless-pre-function": {
  11.         "_meta": {
  12.             "priority": -2000
  13.         },
  14.         "phase": "rewrite",
  15.         "functions": ["return function(conf, ctx)
  16.                     ngx.say(\"serverless-pre-function\");
  17.                     end"]
  18.     }
  19. }

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 插件会优先执行。

注意
  • 自定义插件优先级只会影响插件实例绑定的主体，不会影响该插件的所有实例。比如上面的插件配置属于路由 A，路由 B 上的插件 serverless-post-function 和 serverless-post-function 插件执行顺序不会受到影响，会使用默认优先级。
  • 自定义插件优先级不适用于 Consumer 上配置的插件的 rewrite 阶段。路由上配置的插件的 rewrite 阶段将会优先运行，然后才会运行 Consumer 上除 auth 类插件之外的其他插件的 rewrite 阶段。

  1. 如下配置表示，只有当请求查询参数中 version 值为 v2 时，proxy-rewrite 插件才会执行。

    1. {
    2.     "proxy-rewrite": {
    3.         "_meta": {
    4.             "filter": [
    5.                 ["arg_version", "==", "v2"]
    6.             ]
    7.         },
    8.         "uri": "/anything"
    9.     }
    10. }

  2. 使用下述配置创建一条完整的路由。

    1. {
    2.     "uri": "/get",
    3.     "plugins": {
    4.         "proxy-rewrite": {
    5.             "_meta": {
    6.                 "filter": [
    7.                     ["arg_version", "==", "v2"]
    8.                 ]
    9.             },
    10.             "uri": "/anything"
    11.         }
    13.     "upstream": {
    14.         "type": "roundrobin",
    15.         "nodes": {
    16.             "httpbin.org:80": 1
    17.         }
    18.     }

  3. 当请求中不带任何参数时，proxy-rewrite 插件不会执行，请求将被转发到上游的 /get。

    1. < HTTP/1.1 200 OK
    2. ......
    3. < Server: APISIX/2.15.0
    4. <
    5. {
    6. "args": {},
    7. "headers": {
    8.     "Accept": "*/*",
    9.     "Host": "httpbin.org",
    10.     "User-Agent": "curl/7.79.1",
    11.     "X-Amzn-Trace-Id": "Root=1-62eb6eec-46c97e8a5d95141e621e07fe",
    12.     "X-Forwarded-Host": "httpbin.org"
    13. },
    14. "origin": "127.0.0.1, 117.152.66.200",
    15. "url": "http://httpbin.org/get"
    16. }

  4. 当请求中携带参数 version=v2 时，proxy-rewrite 插件执行，请求将被转发到上游的 /anything:

    1. curl -v /dev/null http://127.0.0.1:9080/get?version=v2 -H"host:httpbin.org"
    1. < HTTP/1.1 200 OK
    2. ......
    3. < Server: APISIX/2.15.0
    4. <
    5. {
    6. "args": {
    7.     "version": "v2"
    8. },
    9. "data": "",
    10. "files": {},
    11. "form": {},
    12. "headers": {
    13.     "Accept": "*/*",
    14.     "Host": "httpbin.org",
    15.     "User-Agent": "curl/7.79.1",
    16.     "X-Amzn-Trace-Id": "Root=1-62eb6f02-24a613b57b6587a076ef18b4",
    17.     "X-Forwarded-Host": "httpbin.org"
    18. },
    19. "json": null,
    20. "method": "GET",
    21. "origin": "127.0.0.1, 117.152.66.200",
    22. "url": "http://httpbin.org/anything?version=v2"
    23. }

APISIX 的插件是热加载的，不管你是新增、删除还是修改插件，都不需要重启服务。

只需要通过 Admin API 发送一个 HTTP 请求即可：

Plugin - 图4注意

如果你已经在路由规则里配置了某个插件（比如在 Route 的 字段里面添加了它），然后在配置文件中禁用了该插件，在执行路由规则时则会跳过该插件。