kong插件开发——插件配置

简介

大多数情况下，您的插件可以配置为满足您的所有用户需求。当插件被执行的时候，您的插件的配置存储在Kong的数据存储区中，以检索它并将其传递给handler.lua方法。

配置由Kong中的Lua表组成，我们称之为 schema。它包含用户在通过Admin API启用插件时将设置的键/值属性。Kong为您提供了一种验证用户插件配置的方法。

当用户向Admin API发出请求以启用或更新给定Service，Route和/或Consumer上的插件时，将根据您的架构schema插件的配置。

例如，用户执行以下请求：

$ curl -X POST http://kong:8001/services/<service-name-or-id>/plugins/ \
    -d "name=my-custom-plugin" \
    -d "config.foo=bar"

如果配置对象的所有config都根据您的模式有效，则API将返回201 Created，并且插件将与其配置一起存储在数据库中（在这种情况下为{foo =“bar”}）。如果配置无效，Admin API将返回400 Bad Request和相应的错误消息。

模块

kong.plugins.<plugin_name>.schema

schema.lua规范

此模块将返回一个Lua表，其中包含将定义用户以后如何配置插件的属性的属性。
可用的属性是：

插件继承了一些默认字段，它们是:

在大多数情况下，您可以忽略其中的大部分，并使用默认值。或者用户在启用插件时指定值。
下面是一个模板schema。如下实例，文件路径https://github.com/Kong/kong/blob/master/kong/db/schema/typedefs.lua

local typedefs = require "kong.db.schema.typedefs"
return {
  name = "<plugin-name>",
  fields = {
    {
      -- this plugin will only be applied to Services or Routes
      consumer = typedefs.no_consumer
    },
    {
      -- this plugin will only run within Nginx HTTP module
      protocols = typedefs.protocols_http
    },
    {
      config = {
        type = "record",
        fields = {
          -- Describe your plugin's configuration's schema here.        
        },
      },
    },
  },
  entity_checks = {
    -- Describe your plugin's entity validation rules
  },
}

描述您的配置schema

schema.lua文件的config.fields自选描述了插件配置的schema。它是一个灵活的键/值表，其中每个键都是插件的有效配置属性，每个键都是一个描述该属性规则的表。例如：

{
  name = "<plugin-name>",
  fields = {
    config = {
      type = "record",
      fields = {
        {
          some_string = {
            type = "string",
            required = false,
          },
        },
        {
          some_boolean = {
            type = "boolean",
            default = false,
          },
        },
        {
          some_array = {
            type = "array",
            elements = {
              type = "string",
              one_of = {
                "GET",
                "POST",
                "PUT",
                "DELETE",
              },
            },
          },
        },
      },
    },
  },
}

以下是属性的规则列表：

• type:将转换从请求参数中检索的值。如果类型不是本机Lua类型之一，则会对其执行自定义验证：
  • id:必须是string
  • timestamp:必须是nember
  • uri:必须是有效的URL
  • array:必须是整数索引表（相当于Lua中的数组）。在Admin API中，可以通过在请求的正文中使用不同值的属性键的多次来发送这样的数组，或者通过单个body参数以逗号分隔。
• unique:此属性对插件配置没有意义，但在插件需要在数据存储区中存储自定义实体时使用。
• schema:如果您需要对嵌套属性进行深化验证，则此字段允许您创建嵌套模式。模式验证是递归的。任何级别的嵌套都是有效的，但请记住，这会影响插件的可用性。
• 附加到配置对象但schema中不存在的任何属性也将使所述配置无效。

例子

key-auth插件的schema.lua文件定义了API密钥的可接受参数名称的默认列表，以及默认设置为false的布尔值：

-- schema.lua
return {
  no_consumer = true,
  fields = {
    key_names = {type = "array", required = true, default = {"apikey"}},
    hide_credentials = {type = "boolean", default = false}
  }
}

于是，当在handler.lua中实现插件的access()函数并且用户使用默认值启用插件时，您可以如下：

-- handler.lua
local BasePlugin = require "kong.plugins.base_plugin"
local CustomHandler = BasePlugin:extend()

function CustomHandler:new()
  CustomHandler.super.new(self, "my-custom-plugin")
end

function CustomHandler:access(config)
  CustomHandler.super.access(self)

  kong.log.inspect(config.key_names)        -- {"apikey"}
  kong.log.inspect(config.hide_credentials) -- false
end

return CustomHandler

请注意，上面的示例使用插件开发工具包(PDK)的kong.log.inspect函数将这些值打印到Kong日志中。

一个更复杂的示例，可用于最终日志记录插件：

-- schema.lua
local typedefs = require "kong.db.schema.typedefs"


return {
  name = "my-custom-plugin",
  fields = {
    {
      config = {
        type = "record",
        fields = {
          {
            environment = {
              type = "string",
              required = true,
              one_of = {
                "production",
                "development",
              },
            },
          },
          {
            server = {
              type = "record",
              fields = {
                {
                  host = typedefs.host {
                    default = "example.com",
                  },
                },
                {
                  port = {
                    type = "number",
                    default = 80,
                    between = {
                      0,
                      65534
                    },
                  },
                },  
              },
            },
          },
        },
      },
    },
  },
}

这样的配置将允许用户将配置发布到您的插件，如下所示：

curl -X POST http://kong:8001/services/<service-name-or-id>/plugins \
    -d "name=my-custom-plugin" \
    -d "config.environment=development" \
    -d "config.server.host=http://localhost"

以下内容将在handler.lua中提供：

-- handler.lua
local BasePlugin = require "kong.plugins.base_plugin"
local CustomHandler = BasePlugin:extend()

function CustomHandler:new()
  CustomHandler.super.new(self, "my-custom-plugin")
end

function CustomHandler:access(config)
  CustomHandler.super.access(self)

  kong.log.inspect(config.environment) -- "development"
  kong.log.inspect(config.server.host) -- "http://localhost"
  kong.log.inspect(config.server.port) -- 8080
end

return CustomHandler

您还可以在Key-Auth插件源代码中查看schema的真实示例。

参考
https://docs.konghq.com/2.2.x/plugin-development/plugin-configuration/
https://docs.konghq.com/1.1.x/plugin-development/plugin-configuration/