插件开发

Apache APISIX 提供了两种方式来添加新的功能。

  1. 修改 Apache APISIX 的源代码并重新发布 (不推荐)。
  2. 配置 和 extra_lua_cpath 在 conf/config.yaml 以加载你自己的代码文件。 你应该给自己的代码文件起一个不包含在原来库中的名字，而不是使用相同名称的代码文件，但是如果有需要，你可以使用这种方式覆盖内置的代码文件。

比如，你可以创建一个目录目录结构，像下面这样：

note

如果你需要自定义插件的目录，请在该目录下创建 /apisix/plugins 的子目录。

接着，在 conf/config.yaml 文件中添加如下的配置：

  1. apisix:
  2.     ...
  3.     extra_lua_path: "/path/to/example/?.lua"

现在使用 require "apisix.plugins.3rd-party" 会加载你自己的插件， 比如 require "apisix.plugins.jwt-auth"会加载 jwt-auth 插件。

可能你会想覆盖一个文件中的函数，你可以在 conf/config.yaml 文件中配置 lua_module_hook 来使你的 hook 生效。

你的配置可以像下面这样：

  1. apisix:
  2.     ...
  3.     extra_lua_path: "/path/to/example/?.lua"
  4.     lua_module_hook: "my_hook"

当 APISIX 启动的时候，example/my_hook.lua 就会被加载，这时你可以使用这个钩子在 APISIX 中来全局替换掉一个方法。 这个例子： 可以在项目的 example 路径下被找到。

检查外部依赖

如果你的插件，涉及到一些外部的依赖和三方库，请首先检查一下依赖项的内容。 如果插件需要用到共享内存，需要在 ，例如：

  1. # put this in config.yaml:
  2. nginx_config:
  3.     http_configuration_snippet: |
  4.         # for openid-connect plugin
  5.         lua_shared_dict discovery             1m; # cache for discovery metadata documents
  6.         lua_shared_dict jwks                  1m; # cache for JWKs
  7.         lua_shared_dict introspection        10m; # cache for JWT verification results

插件本身提供了 init 方法。方便插件加载后做初始化动作。

注：如果部分插件的功能实现，需要在 Nginx 初始化启动，则可能需要在 apisix/init.lua 文件的初始化方法 http_init 中添加逻辑，并且可能需要在 apisix/cli/ngx_tpl.lua 文件中，对 Nginx 配置文件生成的部分，添加一些你需要的处理。但是这样容易对全局产生影响，根据现有的插件机制，我们不建议这样做，除非你已经对代码完全掌握。

插件命名，优先级和其他

给插件取一个很棒的名字，确定插件的加载优先级，然后在 conf/config.yaml 文件中添加上你的插件名。例如 example-plugin 这个插件， 需要在代码里指定插件名称（名称是插件的唯一标识，不可重名），在 apisix/plugins/example-plugin.lua 文件中可以看到：

  1. local plugin_name = "example-plugin"
  3. local _M = {
  4.     version = 0.1,
  5.     priority = 0,
  6.     name = plugin_name,
  7.     schema = schema,
  8.     metadata_schema = metadata_schema,
  9. }

注：新插件的优先级（ priority 属性 ）不能与现有插件的优先级相同，您可以使用 的 /v1/schema 方法查看所有插件的优先级。另外，同一个阶段里面，优先级 ( priority ) 值大的插件，会优先执行，比如 example-plugin 的优先级是 0 ，ip-restriction 的优先级是 3000 ，所以在每个阶段，会先执行 ip-restriction 插件，再去执行 example-plugin 插件。这里的“阶段”的定义，参见后续的 确定执行阶段 这一节。对于你的插件，建议采用 1 到 99 之间的优先级。

在 conf/config-default.yaml 配置文件中，列出了启用的插件（都是以插件名指定的）：

  1. plugins:                          # plugin list
  2.   - limit-req
  3.   - limit-count
  4.   - limit-conn
  5.   - key-auth
  6.   - prometheus
  7.   - node-status
  8.   - jwt-auth
  9.   - zipkin
  10.   - ip-restriction
  11.   - grpc-transcode
  12.   - serverless-pre-function
  13.   - serverless-post-function
  14.   - openid-connect
  15.   - proxy-rewrite
  16.   - redirect
  17.   ...

注：先后顺序与执行顺序无关。

特别需要注意的是，如果你的插件有新建自己的代码目录，那么就需要修改 Makefile 文件，新增创建文件夹的操作，比如：

  1. $(INSTALL) -d $(INST_LUADIR)/apisix/plugins/skywalking
  2. $(INSTALL) apisix/plugins/skywalking/*.lua $(INST_LUADIR)/apisix/plugins/skywalking/

_M 中还有其他字段会影响到插件的行为。

  1. local _M = {
  2.     ...
  3.     type = 'auth',
  4.     run_policy = 'prefer_route',
  5. }

如果你的插件需要跟 consumer 一起使用，需要把 type 设置成 auth。详情见下文。

定义插件的配置项，以及对应的 JSON Schema 描述，并完成对 JSON 的校验，这样方便对配置的数据规格进行验证，以确保数据的完整性以及程序的健壮性。同样，我们以 example-plugin 插件为例，看看他的配置数据：

我们看下他的 Schema 描述：

  1. local schema = {
  2.     type = "object",
  3.     properties = {
  4.         i = {type = "number", minimum = 0},
  5.         s = {type = "string"},
  6.         t = {type = "array", minItems = 1},
  7.         ip = {type = "string"},
  8.     },
  9.     required = {"i"},
  10. }

这个 schema 定义了一个非负数 i，字符串 s，非空数组 t，和 跟 port。只有 i 是必需的。

同时，需要实现 check_schema(conf) 方法，完成配置参数的合法性校验。

  1. function _M.check_schema(conf)
  2.     return core.schema.check(schema, conf)
  3. end

注：项目已经提供了 core.schema.check 公共方法，直接使用即可完成配置参数校验。

另外，如果插件需要使用一些元数据，可以定义插件的 metadata_schema ，然后就可以通过 admin api 动态的管理这些元数据了。如：

  1. local metadata_schema = {
  2.     type = "object",
  3.     properties = {
  4.         ikey = {type = "number", minimum = 0},
  5.         skey = {type = "string"},
  6.     },
  7.     required = {"ikey", "skey"},
  8. }
  10. local plugin_name = "example-plugin"
  12. local _M = {
  13.     version = 0.1,
  14.     priority = 0,        -- TODO: add a type field, may be a good idea
  15.     name = plugin_name,
  16.     schema = schema,
  17.     metadata_schema = metadata_schema,
  18. }

你可能之前见过 key-auth 这个插件在它的模块定义时设置了 type = 'auth'。 当一个插件设置 type = 'auth'，说明它是个认证插件。

认证插件需要在执行后选择对应的 consumer。举个例子，在 key-auth 插件中，它通过 apikey 请求头获取对应的 consumer，然后通过 consumer.attach_consumer 设置它。

为了跟 consumer 资源一起使用，认证插件需要提供一个 consumer_schema 来检验 consumer 资源的 plugins 属性里面的配置。

下面是 key-auth 插件的 consumer 配置：

  1. {
  2.   "username": "Joe",
  3.   "plugins": {
  4.     "key-auth": {
  5.       "key": "Joe's key"
  6.     }
  7.   }
  8. }

你在创建 时会用到它。

为了检验这个配置，这个插件使用了如下的 schema:

  1. local consumer_schema = {
  2.     type = "object",
  3.     properties = {
  4.         key = {type = "string"},
  5.     },
  6.     required = {"key"},
  7. }

注意 key-auth 的 check_schema(conf) 方法和 example-plugin 的同名方法的区别：

  1. -- key-auth
  2. function _M.check_schema(conf, schema_type)
  3.     if schema_type == core.schema.TYPE_CONSUMER then
  4.         return core.schema.check(consumer_schema, conf)
  5.     else
  6.         return core.schema.check(schema, conf)
  7.     end
  8. end
  1. -- example-plugin
  2. function _M.check_schema(conf, schema_type)
  3.     return core.schema.check(schema, conf)
  4. end

确定执行阶段

根据业务功能，确定你的插件需要在哪个阶段执行。 key-auth 是一个认证插件，所以需要在 rewrite 阶段执行。在 APISIX，只有认证逻辑可以在 rewrite 阶段里面完成，其他需要在代理到上游之前执行的逻辑都是在 access 阶段完成的。

注意：我们不能在 rewrite 和 access 阶段调用 ngx.exit、ngx.redirect 或者 core.respond.exit。如果确实需要退出，只需要 return 状态码和正文，插件引擎将使用返回的状态码和正文进行退出。

除了 OpenResty 的阶段，我们还提供额外的阶段来满足特定的目的：

  • delayed_body_filter

编写执行逻辑

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "methods": ["GET"],
  4.     "uri": "/index.html",
  5.     "id": 1,
  6.     "plugins": {
  7.         "limit-conn": {
  8.             "conn": 1,
  9.             "burst": 0,
  10.             "default_conn_delay": 0.1,
  11.             "rejected_code": 503,
  12.             "key": "remote_addr"
  13.         }
  14.     },
  15.     "upstream": {
  16.         "type": "roundrobin",
  18.             "127.0.0.1:1980": 1
  19.         }
  20. }'

conf 参数是插件的相关配置信息，您可以通过 core.log.warn(core.json.encode(conf)) 将其输出到 error.log 中进行查看，如下所示：

  1. function _M.access(conf, ctx)
  2.     core.log.warn(core.json.encode(conf))
  3.     ......
  4. end

conf:

  1. {
  2.   "rejected_code": 503,
  3.   "burst": 0,
  4.   "default_conn_delay": 0.1,
  5.   "conn": 1,
  6.   "key": "remote_addr"
  7. }

ctx 参数缓存了请求相关的数据信息，您可以通过 core.log.warn(core.json.encode(ctx, true)) 将其输出到 error.log 中进行查看，如下所示：

  1. function _M.access(conf, ctx)
  2.     core.log.warn(core.json.encode(ctx, true))
  3.     ......
  4. end

插件可以注册暴露给公网的接口。以 jwt-auth 插件为例，这个插件为了让客户端能够签名，注册了 GET /apisix/plugin/jwt/sign 这个接口：

  1. local function gen_token()
  2.     -- ...
  3. end
  5. function _M.api()
  6.     return {
  7.         {
  8.             methods = {"GET"},
  9.             uri = "/apisix/plugin/jwt/sign",
  10.             handler = gen_token,
  11.         }
  12.     }
  13. end

注意，注册的接口将不会默认暴露，需要使用来暴露它。

注册控制接口

如果你只想暴露 API 到 localhost 或内网，你可以通过 来暴露它。

Take a look at example-plugin plugin:

  1. local function hello()
  2.     local args = ngx.req.get_uri_args()
  3.     if args["json"] then
  4.         return 200, {msg = "world"}
  5.     else
  6.         return 200, "world\n"
  7.     end
  8. end
  11. function _M.control_api()
  12.     return {
  13.         {
  14.             methods = {"GET"},
  15.             uris = {"/v1/plugin/example-plugin/hello"},
  16.             handler = hello,
  17.         }
  18.     }
  19. end

如果你没有改过默认的 control API 配置，这个插件暴露的 GET /v1/plugin/example-plugin/hello API 只有通过 127.0.0.1 才能访问它。通过以下命令进行测试：

  1. curl -i -X GET "http://127.0.0.1:9090/v1/plugin/example-plugin/hello"

查看更多有关 control API 介绍

注册自定义变量

我们可以在 APISIX 的许多地方使用变量。例如，在 http-logger 中自定义日志格式，用它作为 limit-* 插件的键。在某些情况下，内置的变量是不够的。因此，APISIX 允许开发者在全局范围内注册他们的变量，并将它们作为普通的内置变量使用。

例如，让我们注册一个叫做 a6_labels_zone 的变量来获取路由中 zone 标签的值。

此后，任何对 $a6_labels_zone 的获取操作都会调用注册的获取器来获取数值。

注意，自定义变量不能用于依赖 Nginx 指令的功能，如 access_log_format。

针对功能，完善各种维度的测试用例，对插件做个全方位的测试吧！插件的测试用例，都在 t/plugin 目录下，可以前去了解。 项目测试框架采用的 。 一个测试用例 .t 文件，通常用 __DATA__ 分割成 序言部分 和 数据部分。这里我们简单介绍下数据部分， 也就是真正测试用例的部分，仍然以 key-auth 插件为例：

  1. === TEST 1: sanity
  2. --- config
  3.     location /t {
  4.         content_by_lua_block {
  5.             local plugin = require("apisix.plugins.key-auth")
  6.             local ok, err = plugin.check_schema({key = 'test-key'}, core.schema.TYPE_CONSUMER)
  7.             if not ok then
  8.                 ngx.say(err)
  9.             end
  11.             ngx.say("done")
  12.         }
  13.     }
  14. --- request
  15. GET /t
  16. --- response_body
  17. done
  19. [error]

一个测试用例主要有三部分内容：

  • 程序代码： Nginx location 的配置内容
  • 输入： http 的 request 信息
  • 输出检查： status ，header ，body ，error_log 检查

这里请求 /t ，经过配置文件 location ，调用 content_by_lua_block 指令完成 lua 的脚本，最终返回。 用例的断言是 response_body 返回 “done”，no_error_log 表示会对 Nginx 的 error.log 检查， 必须没有 ERROR 级别的记录。

根据我们在 Makefile 里配置的 PATH，和每一个 .t 文件最前面的一些配置项，框架会组装成一个完整的 nginx.conf 文件， t/servroot 会被当成 Nginx 的工作目录，启动 Nginx 实例。根据测试用例提供的信息，发起 http 请求并检查 http 的返回项， 包括 http status，http response header， http response body 等。