2025实战：Kong自定义插件开发指南（从入门到上线）-优快云博客

2025实战：Kong自定义插件开发指南（从入门到上线）

【免费下载链接】kong Kong是一款高性能的开源API网关，支持多种协议和插件，能够实现API路由、认证、限流等功能，助力企业构建灵活、安全且可扩展的API架构。项目地址: https://gitcode.com/GitHub_Trending/ko/kong

你是否遇到过Kong网关现有插件无法满足业务需求的困境？想添加自定义认证逻辑却不知从何下手？本文将带你从零构建一个完整的Kong插件，掌握从环境搭建到部署上线的全流程。读完本文，你将获得：

插件目录结构的标准化设计方法
核心处理逻辑与配置验证的实现要点
基于官方测试框架的插件验证技巧
无缝集成到Kong网关的部署策略

插件开发基础

Kong作为高性能API网关，其插件系统基于Lua语言和OpenResty框架构建。插件通过拦截请求/响应生命周期的不同阶段实现功能扩展，核心依赖于Kong提供的PDK（Plugin Development Kit）。

工作原理

Kong插件采用链式处理模型，每个插件可在请求处理的多个阶段介入。典型的执行流程包括：

access阶段：请求到达时执行认证、限流等逻辑
header_filter阶段：响应头处理
body_filter阶段：响应体处理
log阶段：请求完成后记录日志

开发环境准备

开发插件需先搭建Kong源码环境：

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/ko/kong
cd kong

# 安装依赖（Ubuntu示例）
sudo apt update && sudo apt install -y automake build-essential git libyaml-dev

# 构建开发环境
make build-venv
. bazel-bin/build/kong-dev-venv.sh
start_services
kong migrations bootstrap

详细环境配置可参考DEVELOPER.md，Windows和macOS用户需查看对应系统的安装指南。

插件目录结构

Kong插件遵循标准化的目录结构，新建插件建议放在kong/plugins/目录下。以my-plugin为例：

kong/plugins/my-plugin/
├── handler.lua      # 核心处理逻辑
├── schema.lua       # 配置验证规则
├── api.lua          # 可选，添加管理API端点
└── migrations/      # 可选，数据库迁移脚本

可参考现有插件如key-auth的结构设计，官方推荐使用插件模板初始化项目。

核心功能实现

1. 定义配置模式（schema.lua）

配置模式使用Lua表结构定义，用于验证管理员输入的插件配置：

local typedefs = require "kong.db.schema.typedefs"

return {
  name = "my-plugin",
  fields = {
    { consumer = typedefs.no_consumer },
    { protocols = typedefs.protocols_http },
    { config = {
        type = "record",
        fields = {
          { timeout = { type = "number", default = 3000, between = {1000, 10000} } },
          { log_level = { type = "string", default = "info", one_of = {"debug", "info", "warn", "error"} } }
        }
      }
    }
  }
}

该文件定义了插件接收的配置参数及其验证规则，Kong Admin API会自动应用这些验证。

2. 实现处理逻辑（handler.lua）

handler.lua是插件核心，通过定义不同阶段的方法实现功能：

local plugin = {
  VERSION = "0.1.0",
  PRIORITY = 1000  -- 优先级，数值越高越先执行
}

-- access阶段处理函数
function plugin:access(conf)
  -- 获取配置值
  local timeout = conf.timeout
  
  -- PDK调用示例：获取请求信息
  local host = kong.request.get_host()
  local path = kong.request.get_path()
  
  -- 业务逻辑实现
  if path == "/protected" then
    -- 验证逻辑...
    if not valid then
      return kong.response.error(403, "Access denied")
    end
  end
end

return plugin

PDK提供了丰富的API，完整文档见PDK参考，常用功能包括：

请求/响应操作：kong.request.get_header()、kong.response.set_header()
日志记录：kong.log.info()、kong.log.err()
缓存操作：kong.cache.get()、kong.cache.set()

3. 关键开发技巧

优先级设置：PRIORITY值决定插件执行顺序，需根据功能需求合理设置
错误处理：使用kong.response.error()返回标准错误响应
性能考量：避免在关键路径执行复杂计算，使用kong.cache缓存数据
配置访问：通过conf参数访问验证后的配置，无需再次校验

测试与调试

单元测试

Kong使用busted框架进行测试，插件测试文件建议放在spec/03-plugins/my-plugin/目录。测试示例：

local helpers = require "spec.helpers"

describe("my-plugin", function()
  local client

  setup(function()
    local bp = helpers.get_db_utils(nil, nil, {"my-plugin"})
    
    -- 创建测试路由和服务
    local service = bp.services:insert({name = "test-service", host = "httpbin.org"})
    local route = bp.routes:insert({paths = {"/test"}, service = service})
    
    -- 启用插件
    bp.plugins:insert({
      name = "my-plugin",
      route = {id = route.id},
      config = {timeout = 3000}
    })

    helpers.start_kong()
    client = helpers.proxy_client()
  end)

  teardown(function()
    client:close()
    helpers.stop_kong()
  end)

  it("should return 200 for valid requests", function()
    local res = client:get("/test/get")
    assert.res_status(200, res)
  end)
end)

运行测试命令：make test-plugins PLUGINS=my-plugin

调试技巧

日志调试：使用kong.log输出调试信息，日志级别通过kong.conf配置
EmmyLua调试：配置IDE远程调试，参考调试指南
实时重载：修改插件代码后执行kong reload无需重启服务

部署与上线

打包插件

推荐使用LuaRocks打包插件：

-- my-plugin-0.1.0-1.rockspec
package = "my-plugin"
version = "0.1.0-1"
source = {
  url = "git+https://gitcode.com/yourusername/my-plugin.git"
}
description = {
  summary = "A Kong plugin for custom authentication",
  license = "MIT"
}
dependencies = {
  "lua >= 5.1"
}
build = {
  type = "builtin",
  modules = {
    ["kong.plugins.my-plugin.handler"] = "handler.lua",
    ["kong.plugins.my-plugin.schema"] = "schema.lua"
  }
}

安装方法

源码安装：

luarocks make my-plugin-0.1.0-1.rockspec

配置加载：在kong.conf中添加：

plugins = bundled,my-plugin  # 确保包含你的插件名

验证安装：

kong plugins list | grep my-plugin

高级功能

数据库集成

如需存储自定义数据，可通过Kong的数据库抽象层实现：

-- 创建自定义实体
local entities = {
  {
    name = "my-plugin-data",
    primary_key = { "id" },
    fields = {
      { id = { type = "id", dao_insert_value = true } },
      { key = { type = "string", required = true, unique = true } },
      { value = { type = "string" } }
    }
  }
}

return { entities = entities }

详细数据库操作参考数据访问层文档

管理API扩展

通过api.lua添加自定义管理端点：

return {
  ["/my-plugin/stats"] = {
    methods = { "GET" },
    handler = function(self, db, helpers)
      -- 实现统计数据查询逻辑
      return kong.response.exit(200, { stats = ... })
    end
  }
}

总结与资源

本文介绍了Kong插件开发的完整流程，从环境搭建到部署上线。关键要点：

遵循标准化目录结构提高兼容性
充分利用PDK提供的API简化开发
编写全面测试确保插件稳定性
采用LuaRocks标准化打包流程

2025实战：Kong自定义插件开发指南（从入门到上线）