一、自定义插件开发基础认知

APISIX作为高性能API网关，其插件系统采用模块化设计，允许开发者通过Lua语言编写自定义逻辑。插件在请求处理流程中的执行顺序由priority字段控制，数值越大优先级越高。每个插件必须实现init、access、header_filter、body_filter和log等标准生命周期钩子，其中access阶段是处理请求逻辑的核心位置。

插件目录结构遵循约定优于配置原则，基础目录为/apisix/plugins/，每个插件需创建独立子目录。以example-plugin为例，标准目录应包含：

/apisix/plugins/example-plugin/
├── handler.lua        # 核心逻辑实现
├── schema.lua         # 参数校验规则
├── access.lua         # 访问阶段逻辑（可选）
└── conf/example.yaml  # 默认配置文件

二、核心开发步骤详解

1. 插件基础结构搭建

在handler.lua中必须实现new()函数创建插件实例，该函数接收conf参数包含配置信息。示例模板如下：

local _M = {}
local ngx = ngx
function _M.new(conf)
    local plugin = {
        conf = conf,
        priority = 1000  -- 设置执行优先级
    }
    return setmetatable(plugin, {__index = _M})
end
function _M.access(conf, ctx)
    -- 请求处理逻辑
    ngx.log(ngx.INFO, "Accessing plugin with config: ", require("cjson").encode(conf))
end
return _M

2. 配置校验机制实现

schema.lua文件定义插件参数的JSON Schema校验规则，支持类型检查、范围验证等。复杂校验可通过custom_validator实现：

local schema = {
    type = "object",
    properties = {
        enable = {type = "boolean", default = true},
        threshold = {type = "number", minimum = 0, maximum = 100}
    },
    required = {"enable"}
}
return {
    version = 1,
    root_schema = schema
}

3. 核心功能开发要点

在access阶段实现业务逻辑时，可通过ctx对象传递数据到后续阶段。示例实现请求限流逻辑：

function _M.access(conf, ctx)
    local key = ngx.var.remote_addr  -- 基于IP限流
    local limit_req = require("resty.limit.req").new(
        "limit_req_store", 10, 5  -- 10r/s，突发5个
    )
    local delay, err = limit_req:incoming(key, true)
    if not delay then
        if err == "rejected" then
            return 429, {message = "Request too frequent"}
        end
        return 500, {message = "Internal error"}
    end
    if delay >= 0.001 then
        ngx.sleep(delay)
    end
end

三、高级功能实现技巧

1. 依赖管理方案

对于复杂插件，建议使用opm包管理器管理第三方依赖。在插件目录创建opm.lock文件声明依赖：

{
  "dependencies": {
    "lua-resty-jwt": "0.2.0",
    "lua-resty-redis": "0.3.0"
  }
}

2. 性能优化策略

• 使用ngx.ctx缓存计算结果避免重复处理
• 异步操作通过ngx.timer.at实现非阻塞
• 复杂计算可启用LuaJIT FFI提升性能

3. 调试与测试方法

开发阶段可通过tail -f /usr/local/apisix/logs/error.log实时查看日志。推荐使用http-loadtest工具进行压力测试：

wrk -t12 -c400 -d30s http://127.0.0.1:9080/hello --timeout 8s

四、生产部署流程

1. 插件注册

通过Admin API动态加载插件：

curl http://127.0.0.1:9180/apisix/admin/plugins/enable \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
-X PUT -d '{
    "name": "example-plugin"
}'

2. 配置热更新

修改插件配置无需重启服务：

curl http://127.0.0.1:9180/apisix/admin/plugins/example-plugin \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
-X PUT -d '{
    "enable": true,
    "threshold": 50
}'

3. 监控指标集成

通过Prometheus暴露插件指标，在conf/config.yaml中配置：

plugin_attr:
  example-plugin:
    collect_metrics: true
    metrics_namespace: "custom_plugin"

五、典型应用场景实践

1. 自定义认证实现

结合JWT实现双因素认证：

function _M.access(conf, ctx)
    local jwt_obj = require("resty.jwt"):new()
    local token = ngx.var.http_authorization
    local jwt, err = jwt_obj:verify(conf.secret, token)
    if not jwt then
        return 401, {message = "Invalid token"}
    end
    -- 验证OTP
    local otp = ngx.req.get_headers()["X-OTP"]
    if otp ~= conf.expected_otp then
        return 401, {message = "OTP verification failed"}
    end
end

2. 请求内容修改

实现请求体动态修改功能：

function _M.body_filter(conf, ctx)
    if not ngx.arg(1) then
        return  -- 结束标记
    end
    local chunk = ngx.arg(1)
    local modified = chunk:gsub("old_text", "new_text")
    ngx.arg(1) = modified
end

六、最佳实践与避坑指南

1. 错误处理：必须捕获所有可能的异常，使用pcall包装关键操作
2. 资源释放：在log阶段关闭数据库连接等资源
3. 配置默认值：通过__index元方法设置合理默认值
4. 版本控制：在schema.lua中维护版本号便于升级
5. 文档规范：编写完整的README.md说明配置参数和使用示例

通过系统掌握上述开发流程和技术要点，开发者能够高效构建满足业务需求的APISIX自定义插件。实际开发中建议先实现核心功能，再逐步完善错误处理和性能优化，最后通过单元测试和压力测试验证插件稳定性。