【免费下载】 Apache APISIX 插件开发完全指南

Apache APISIX 插件开发完全指南

【免费下载链接】apisix The Cloud-Native API Gateway 项目地址: https://gitcode.com/GitHub_Trending/ap/apisix

作为一款高性能 API 网关，Apache APISIX 提供了强大的插件机制，允许开发者扩展其功能。本文将深入讲解如何为 APISIX 开发自定义插件，涵盖从基础概念到高级特性的完整开发流程。

插件开发基础

插件存放位置

APISIX 提供了两种方式来添加自定义插件：

1. 修改源码方式（不推荐）：直接修改 APISIX 源代码并重新分发
2. 外部加载方式（推荐）：通过配置 extra_lua_path 和 extra_lua_cpath 加载自定义代码

推荐的项目结构如下：

├── example
│   └── apisix
│       ├── plugins
│       │   └── custom-plugin.lua
│       └── stream
│           └── plugins
│               └── custom-plugin.lua

在 conf/config.yaml 中添加配置：

apisix:
    extra_lua_path: "/path/to/example/?.lua"

依赖管理

如果插件依赖外部库或共享内存，需要：

1. 检查依赖项是否可用
2. 对于共享内存，在 Nginx 配置中声明：

nginx_config:
    http_configuration_snippet: |
        lua_shared_dict custom_cache 10m;

插件元数据定义

每个插件都需要定义元数据，包括：

local plugin_name = "custom-plugin"

local _M = {
    version = 0.1,
    priority = 100,       -- 执行优先级
    name = plugin_name,   -- 插件唯一标识
    schema = schema,      -- 配置校验规则
    metadata_schema = metadata_schema, -- 元数据校验规则
    type = "auth",        -- 插件类型（可选）
    run_policy = "prefer_route", -- 执行策略
}

关键点说明：

1. priority 决定插件执行顺序，值越大优先级越高
2. 插件名称必须唯一
3. 认证类插件需设置 type = "auth"
4. run_policy 可控制全局和路由级插件的执行策略

配置校验机制

APISIX 使用 JSON Schema 进行配置校验：

local schema = {
    type = "object",
    properties = {
        param1 = {type = "number", minimum = 0},
        param2 = {type = "string", pattern = "^[a-z]+$"},
    },
    required = {"param1"},
}

function _M.check_schema(conf, schema_type)
    return core.schema.check(schema, conf)
end

对于认证类插件，还需要定义 consumer_schema：

local consumer_schema = {
    type = "object",
    properties = {
        key = {type = "string"},
    },
    required = {"key"},
}

function _M.check_schema(conf, schema_type)
    if schema_type == core.schema.TYPE_CONSUMER then
        return core.schema.check(consumer_schema, conf)
    else
        return core.schema.check(schema, conf)
    end
end

敏感字段加密

APISIX 3.1+ 支持自动加密敏感字段：

encrypt_fields = {"password", "db.connection.password"}

需在配置中启用加密功能：

apisix:
    data_encryption:
        enable: true
        keyring:
            - first_encryption_key
            - second_encryption_key

执行阶段选择

APISIX 插件可以在 OpenResty 的不同生命周期阶段执行：

阶段	说明
rewrite	请求重写阶段，适合认证类插件
access	访问控制阶段
header_filter	响应头处理阶段
body_filter	响应体处理阶段
log	日志记录阶段

重要提示：在 rewrite 和 access 阶段禁止直接调用 ngx.exit，应返回状态码和响应体。

核心逻辑实现

插件逻辑通过阶段函数实现，接收两个参数：

function _M.rewrite(conf, ctx)
    -- conf: 插件配置
    -- ctx: 请求上下文
    core.log.warn("Plugin config: ", core.json.encode(conf))
    core.log.warn("Request context: ", core.json.encode(ctx, true))
    
    -- 业务逻辑实现...
end

API 扩展机制

公共 API

注册可供外部访问的 API：

function _M.api()
    return {
        {
            methods = {"GET"},
            uri = "/custom/api",
            handler = function()
                return 200, {message = "Hello from plugin"}
            end
        }
    }
end

需要通过 public-api 插件暴露。

控制 API

注册仅供内部访问的 API：

function _M.control_api()
    return {
        {
            methods = {"GET"},
            uris = {"/v1/plugin/custom/hello"},
            handler = function()
                return 200, "Internal API"
            end
        }
    }
end

默认通过 127.0.0.1:9090 访问。

自定义变量

注册全局可用变量：

core.ctx.register_var("custom_var", function(ctx)
    return ctx.var.http_x_custom_header or "default"
end)

之后可通过 $custom_var 引用。

测试开发

APISIX 使用 test-nginx 框架进行测试，测试用例通常包括：

=== TEST 1: basic validation
--- config
    location /t {
        content_by_lua_block {
            -- 测试代码
        }
    }
--- request
GET /t
--- response_body
expected response
--- error_code: 200

测试要点：

1. 配置验证
2. 正常流程测试
3. 异常情况测试
4. 性能基准测试

最佳实践

1. 优先使用外部加载方式开发插件
2. 合理设置插件优先级，避免与内置插件冲突
3. 完善配置校验和错误处理
4. 为敏感信息启用加密存储
5. 编写全面的测试用例
6. 考虑插件性能影响

通过本文的指导，您应该能够开发出功能完善、安全可靠的 APISIX 插件，为您的 API 网关扩展所需功能。

【免费下载链接】apisix The Cloud-Native API Gateway 项目地址: https://gitcode.com/GitHub_Trending/ap/apisix