使用 Lua 创建自定义插件
APISIX 的主要功能之一是其通过 插件 的可扩展性。除了各种现有插件外,APISIX 还允许你构建自定义插件以添加额外功能并使用自定义流程管理 API 流量。通常,你使用 Lua 编程语言来实现新插件。APISIX 分 阶段 处理请求,相关的插件逻辑在请求路由期间的每个阶段执行。
本指南将引导你完成为 APISIX 开发一个新的自定义 Lua 插件的示例过程。
前置条件
- 安装 Docker。
- 安装 cURL 以向服务发送请求进行验证。
- 按照 快速入门教程 在 Docker 或 Kubernetes 中启动一个新的 APISIX 实例。
- 如果启用了 Admin API 身份验证,请将管理员角色的密钥导出为
ADMIN_API_KEY。
开发文件代理插件
在本节中,你将使用 Lua 为 APISIX 创建一个名为 file-proxy 的新自定义插件。此插件将用于通过 API 公开静态文件(YAML、JSON、JavaScript、CSS 或图像文件)并从指定的 URL 获取文件。
例如,API 用户可以通过指定的 URL http://127.0.0.1:9080/openapi.yaml 访问 openapi.yaml 文件。
创建 Lua 文件
为插件源代码创建一个名为 file-proxy.lua 的新 Lua 文件。
导入模块
为 file-proxy 插件导入必要的模块:
local core = require("apisix.core")
local io = require("io")
local ngx = ngx
定义插件名称
为插件声明一个唯一的名称:
local plugin_name = "file-proxy"
定义插件架构
为插件参数创建一个架构。架构定义了可用参数及其数据类型、属性、默认值、有效值等。
file-proxy 示例仅接受 /usr/local/apisix/openapi.yaml,也就是下文创建的公开规范文件。Schema 会拒绝其他字面路径,access 处理函数在打开文件前也会再次检查解析后的值。请勿使用教程插件提供凭证或其他私有文件。
local allowed_path = "/usr/local/apisix/openapi.yaml"
local plugin_schema = {
type = "object",
properties = {
path = {
type = "string",
enum = {allowed_path}
},
},
required = {"path"}
}
❶ 要服务的文件的路径。
❷ 路径设置为必需参数。
定义 Lua 模块表
为插件定义属性 version、priority、name 和 schema。name 和 schema 是之前定义的插件名称和架构。version 和 priority 由 APISIX 用于管理插件。
local _M = {
version = 1.0,
priority = 1000,
name = plugin_name,
schema = plugin_schema
}
❶ version:该字段通常是指当前正在使用的版本。如果你发布并更新你的插件逻辑,它将是 1.1