APISIX自定义插件开发指南：从零到一实现核心功能扩展

一、为什么需要自定义插件？

APISIX作为高性能API网关，其核心优势在于灵活的插件机制。默认提供的认证、限流、日志等插件已覆盖80%的通用场景，但在以下场景中，自定义插件成为必要选择：

业务逻辑封装：将企业内部特有的鉴权规则、数据转换逻辑封装为独立插件
性能优化：针对特定业务场景实现轻量级缓存、协议转换等高性能组件
生态集成：与私有云、内部系统等非标准组件进行深度集成
创新功能验证：快速验证新功能对网关性能的影响

以某金融平台为例，其通过自定义插件实现了：

基于设备指纹的二次认证
请求体敏感字段脱敏处理
自定义协议到HTTP的转换

二、插件开发环境准备

2.1 开发工具链

OpenResty环境：APISIX基于OpenResty构建，需安装1.15.8+版本
Lua版本：5.1+（APISIX 2.x）或LuaJIT 2.1（推荐）
测试工具：
- wrk：进行压力测试
- curl：验证插件行为
- stapxx：系统级性能分析

2.2 代码结构规范

插件代码应遵循APISIX约定的目录结构：

/apisix/plugins/
  ├── your-plugin/          # 插件目录
  │   ├── handler.lua       # 核心处理逻辑
  │   ├── schema.lua        # 配置校验规则
  │   ├── access.lua        # 访问阶段逻辑（可选）
  │   ├── header_filter.lua # 头部处理阶段（可选）
  │   └── ...                # 其他阶段实现

三、自定义插件开发六步法

3.1 创建基础插件框架

-- /apisix/plugins/your-plugin/handler.lua
local plugin_name = "your-plugin"
local schema = require(plugin_name .. ".schema")
local _M = {
    version = 0.1,
    priority = 1000,  -- 执行优先级
    name = plugin_name,
    schema = schema.schema,
}
function _M.check_schema(conf, schema_type)
    -- 配置校验逻辑
    return core.schema.check(schema[schema_type or "default"], conf)
end
-- 必须实现的插件生命周期方法
function _M.init() end
function _M.destroy() end
-- 插件执行入口（根据阶段选择实现）
function _M.access(conf, ctx)
    -- 访问阶段处理逻辑
end
function _M.header_filter(conf, ctx)
    -- 响应头处理逻辑
end
return _M

3.2 定义配置校验规则

-- /apisix/plugins/your-plugin/schema.lua
local schema = {
    default = {
        type = "object",
        properties = {
            enable = {type = "boolean", default = true},
            threshold = {type = "number", minimum = 0},
            exclude_paths = {
                type = "array",
                items = {type = "string"},
                default = {}
            }
        },
        required = {"threshold"},
        additionalProperties = false
    }
}
return {schema = schema}

3.3 实现核心业务逻辑

以限流插件为例，展示访问阶段实现：

function _M.access(conf, ctx)
    local uri = ctx.var.uri
    local client_ip = ctx.var.remote_addr
    -- 排除特定路径
    for _, path in ipairs(conf.exclude_paths) do
        if ngx.re.match(uri, path, "jo") then
            return
        end
    end
    -- 限流逻辑实现
    local key = "rate_limit:" .. client_ip
    local limit_req = require("resty.limit.req")
    local limit, err = limit_req.new("limit_req_store", 100, 30)  -- 100r/s, burst 30
    if not limit then
        ngx.log(ngx.ERR, "failed to instantiate a resty.limit.req object: ", err)
        return 500
    end
    local delay, err = limit:incoming(key, true)
    if not delay then
        if err == "rejected" then
            return 429, {message = "Request rejected due to rate limiting"}
        end
        ngx.log(ngx.ERR, "failed to limit req: ", err)
        return 500
    end
    if delay >= 0.001 then
        -- 实际请求需要延迟delay秒后继续执行
        local sleep = delay * 1000  -- 转换为ms
        ngx.sleep(sleep)
    end
end

3.4 插件注册与配置

修改配置文件：

# conf/config.yaml
plugins:
- ...
- your-plugin
plugin_attr:
your-plugin:
 threshold: 1000
 exclude_paths:
   - "/admin/.*"
   - "/healthz"

动态加载插件（无需重启）：

curl http://127.0.0.1:9180/apisix/admin/plugins/reload -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT

3.5 测试验证方法论

单元测试：
```lua
— t/plugin/your-plugin.t
use lib “lib”;
local core = require(“apisix.core”)
local plugin = require(“apisix.plugins.your-plugin”)

describe(“your-plugin test”, function()
it(“test schema validation”, function()
local conf = {threshold = 100}
local ok, err = plugin.check_schema(conf)
assert(ok, err)
end)

it("test rate limiting", function()
    -- 模拟请求上下文
    local ctx = {var = {remote_addr = "127.0.0.1", uri = "/test"}}
    local conf = {threshold = 1, exclude_paths = {}}
    -- 第一次请求应通过
    local code, body = plugin.access(conf, ctx)
    assert(not code, "first request should pass")
    -- 第二次请求应被限流
    code, body = plugin.access(conf, ctx)
    assert(code == 429, "second request should be limited")
end)

end)


2. **集成测试**：
```bash
# 发送测试请求
curl -i http://127.0.0.1:9080/test
HTTP/1.1 200 OK
...
# 超过阈值后测试
for i in {1..2}; do curl http://127.0.0.1:9080/test; done
HTTP/1.1 429 Too Many Requests
...

3.6 性能调优技巧

共享字典优化：

-- 在init阶段初始化共享内存
function _M.init()
 local dict_conf = {
     name = "your_plugin_dict",
     share_type = "plugin",  -- 或"all_workers"
     timeout = 60
 }
 local ok, err = core.config.new(dict_conf)
 if not ok then
     ngx.log(ngx.ERR, "failed to create dict: ", err)
 end
end

LuaJIT优化：

使用local关键字减少全局查找
避免在热路径中创建新表
使用FFI调用C函数处理计算密集型任务

四、常见问题解决方案

4.1 插件不生效排查

检查conf/config.yaml中插件是否启用
验证插件配置语法：
```
apisix check --config conf/config.yaml
```
检查APISIX日志：
```
tail -f logs/error.log
```

4.2 性能瓶颈定位

使用ngx.shared.DICT统计插件执行时间

通过火焰图分析：

# 生成火焰图
perf record -F 99 -g -p $(pgrep -f nginx)
perf script | stackcollapse-perf.pl | flamegraph.pl > flamegraph.svg

4.3 版本兼容性处理

APISIX版本	Lua版本要求	关键变更
2.x	5.1+	插件生命周期方法变更
3.x	LuaJIT 2.1	支持多阶段插件

五、最佳实践建议

插件拆分原则：
- 每个插件聚焦单一职责
- 复杂逻辑拆分为多个协同插件
- 示例：将鉴权与日志拆分为独立插件
配置管理：
- 提供合理的默认值
- 支持动态更新（通过Admin API）
- 实现配置变更回调
错误处理：
- 区分可恢复错误与致命错误
- 提供详细的错误日志
- 实现优雅降级机制
文档规范：
```markdown

插件名称

功能描述

清晰描述插件的核心功能

配置参数

参数名	类型	默认值	说明
enable	bool	true	是否启用插件

示例配置

plugins:
  - your-plugin:
      threshold: 100

性能指标

QPS影响：<5%
内存开销：每个请求约2KB
```

六、进阶开发方向

多阶段插件开发：
- 实现rewrite、log等阶段逻辑
- 示例：请求重写+日志记录组合插件
WASM插件支持：
- 通过Proxy-WASM实现高性能扩展
- 示例：用Rust编写WASM插件
gRPC插件开发：
- 处理gRPC元数据
- 实现gRPC到HTTP的转换逻辑
AI集成插件：
- 调用LLM模型进行请求分析
- 实现动态路由决策

通过本文的详细指导，开发者可以系统掌握APISIX自定义插件的开发方法，从基础框架搭建到性能优化，实现网关功能的深度定制。实际开发中，建议遵循”最小可行插件”原则，先实现核心功能，再逐步完善周边特性，确保插件的稳定性和可维护性。

APISIX自定义插件开发指南：从零到一实现核心功能扩展

APISIX自定义插件开发指南：从零到一实现核心功能扩展

一、为什么需要自定义插件？

二、插件开发环境准备

2.1 开发工具链

2.2 代码结构规范

三、自定义插件开发六步法

3.1 创建基础插件框架

3.2 定义配置校验规则

3.3 实现核心业务逻辑

3.4 插件注册与配置

3.5 测试验证方法论

3.6 性能调优技巧

四、常见问题解决方案

4.1 插件不生效排查

4.2 性能瓶颈定位

4.3 版本兼容性处理

五、最佳实践建议

插件名称

功能描述

配置参数

示例配置

性能指标

六、进阶开发方向