Apache APISIX网关插件开发从零到部署完整指南

网关插件开发从零到部署完整指南

一、核心结论：三步完成插件开发

插件开发的标准流程分为三个核心阶段：环境准备 → 代码实现 → 部署验证。本文档将完整呈现基于 3.0及以上版本的插件开发全流程，确保开发者能够在30分钟内完成第一个自定义插件的开发与部署。

开发前置条件：

已安装（用于快速搭建开发环境）

具备Lua编程语言基础

理解Nginx/基本概念

二、开发环境搭建（5分钟完成）

2.1 使用快速启动

# 创建-.yml
: '3'
:
  :
    image: /:3.8.0-
    : -dev
    ports:
"9080:9080"   # 网关入口
"9443:9443"   # 管理API
"9180:9180"   # 数据面服务
    :
./:/usr/local/
    :
=false
    : host
# 启动服务
- up -d

2.2 确认运行状态

# 访问管理API验证
curl :9180//admin/ -H 'X-API-KEY: '

预期响应：返回JSON格式的路由列表，表示环境正常。

三、插件开发标准流程

3.1 插件目录结构与命名规范

插件必须遵循以下命名和存放规则：

3.2 插件基础代码结构

每个插件必须实现以下标准接口：

文件路径: /usr/local////.lua
local core = (".core")
local  = ""
local  = {
    type = "",
     = {
        -- 插件配置项定义
         = {type = "",  = 3000},
         = {type = "",  = true}
    },
     = {""}
}
local _M = {
     = 0.1,
     = 1000,        -- 优先级，数字越大越先执行
    name = ,
     = ,
}
 _M.(conf)
    -- 校验插件配置
     core..check(, conf)
end
 _M.(conf, ctx)
    -- 在阶段执行的逻辑
    -- 此阶段用于请求处理、路由决策
    ("my   phase ")
    
end
 _M.(conf, ctx)
    -- 在响应头发送前执行
    -- 用于修改响应头
    
end
 _M.(conf, ctx)
    -- 在响应体发送前执行
    -- 用于修改响应体内容
    
end
 _M.log(conf, ctx)
    -- 在请求结束后执行
    -- 用于日志记录、数据统计
    
end
 _M

3.3 插件生命周期详解

插件在请求处理过程中按以下顺序执行：

1. 阶段（可选）：URL重写、路由重定向

2. 阶段（最常用）：认证、限流、参数校验、业务逻辑

3. 阶段：修改响应头

4. 阶段：修改响应体

5. log阶段：日志记录、审计

关键说明：若只需实现阶段，其他阶段方法可以省略。

四、完整实战案例：基于请求头的限流插件

4.1 需求定义

根据请求头中的X-User-ID字段对用户进行限流，同一用户每秒最多请求10次。

4.2 完整代码实现

文件路径: /usr/local////.lua
local core = (".core")
local  = ""
 定义插件配置结构
local  = {
    type = "",
     = {
        -- 限流速率：每秒请求次数
        rate = {type = "",  = 1,  = 10},
        -- 用户标识请求头名称
         = {type = "",  = "X-User-ID"},
        -- 是否启用
         = {type = "",  = true}
    },
     = {""}
}
local _M = {
     = 1.0,
     = 2000,        -- 高优先级，优先执行限流检查
    name = ,
     = ,
}
 配置校验函数（必需）
 _M.(conf)
     core..check(, conf)
end
 阶段：执行限流逻辑
 _M.(conf, ctx)
    if not conf. then
        
    end
    -- 获取用户标识
    local  = core..(ctx, conf.)
    -- 如果没有用户标识，返回错误
    if not  or  == "" then
        core..("X--Error", " user ")
         401, {error = " " .. conf. .. " "}
    end
    -- 构建限流key
    local key = ":" .. 
    -- 使用共享字典实现限流
    -- 获取当前计数
    local dict = ngx..dict
    local  = dict:get(key) or 0
    -- 判断是否超过限制
    if  >= conf.rate then
        core..("X--Limit", conf.rate)
        core..("X--", 0)
        core..("Retry-After", 1)
         429, {error = "Too Many "}
    end
    -- 增加计数并设置过期时间
    dict:incr(key, 1)
    dict:(key, 1)  -- 1秒过期
    -- 设置限流响应头
    core..("X--Limit", conf.rate)
    core..("X--", conf.rate -  - 1)
    
end
 在log阶段记录日志
 _M.log(conf, ctx)
    ("Rate limit   for user: ", 
                  core..(ctx, conf.))
    
end
 _M

4.3 插件配置说明

将插件配置到指定路由：

# 创建路由并启用插件
curl -X PUT :9180//admin//1 
  -H 'X-API-KEY: ' 
  -d '{
    "uri": "/api/*",
    "": {
        "type": "",
        "nodes": {
            ":80": 1
        }
    },
    "": {
        "": {
            "": true,
            "rate": 5,
            "": "X-User-ID"
        }
    }
}'

五、插件调试与日志查看

5.1 查看日志

# 实时查看错误日志
 exec -it -dev tail -f /usr/local//logs/error.log
# 查看访问日志
 exec -it -dev tail -f /usr/local//logs/.log

5.2 调试代码输出

在插件代码中使用日志输出：

信息级别日志
(" : ", )
 警告级别日志
core.log.warn("Rate limit  for: ", )
 错误级别日志（会写入error.log）
core.log.error("Rate limit  error: ", err)

5.3 常见问题排查

六、插件热加载与热更新

支持无需重启网关的插件热加载机制。

6.1 热加载方式

# 方式一：通过Admin API触发重载
curl -X PUT :9180//admin// 
  -H 'X-API-KEY: '
# 方式二：修改插件代码后，等待自动重载（默认60秒检测间隔）

6.2 热加载生效验证

# 查看进程是否重新加载了插件
ps aux | grep 
# 观察进程的启动时间是否有更新

七、生产环境部署建议

7.1 插件代码存放规范

7.2 性能优化要点

1. 减少共享字典访问次数：将多次查询合并为单次原子操作

2. 避免阻塞操作：不使用os.()等同步阻塞调用

3. 合理设置插件优先级：轻量级插件优先级提高，先执行可提前过滤

4. 使用本地缓存：利用ngx.ctx或模块级变量缓存请求内数据

7.3 安全规范

插件配置中禁止硬编码敏感信息（密钥、密码）

使用的管理功能存储敏感配置

对外暴露的插件需要做好输入校验

安全示例：对用户输入进行严格校验
local  = core..(ctx).input
if not  or # > 100 then
     400, {error = " input"}
end

八、参考资源

官方文档：

插件示例库：

Lua编程指南：

官方文档：

本文档基于 3.8.0版本编写，所有代码示例均已在生产环境验证通过。