插件开发全攻略：从零构建Kong生态贡献者的第一行代码

插件开发全攻略：从零构建Kong生态贡献者的第一行代码

【免费下载链接】kong 🦍 The Cloud-Native API Gateway and AI Gateway. 项目地址: https://gitcode.com/gh_mirrors/kon/kong

你是否曾想为Kong生态添砖加瓦，却困于不知如何开始？作为云原生API网关的领军项目，Kong的强大生态离不开社区贡献者的持续创新。本文将带你穿越插件开发的迷雾，从环境搭建到代码提交，一站式掌握Kong社区贡献的全流程，让你的创意快速融入全球最活跃的API网关生态。

开发环境极速搭建

工欲善其事，必先利其器。Kong插件开发需要特定的环境配置，我们已为你准备好最精简的搭建步骤。

基础依赖安装

根据你的操作系统，执行以下命令安装核心依赖：

Ubuntu/Debian

sudo apt update && sudo apt install -y automake build-essential curl git libyaml-dev libprotobuf-dev m4 perl pkg-config procps unzip valgrind zlib1g-dev

Fedora/RHEL

dnf install -y automake gcc gcc-c++ git libyaml-devel make patch perl perl-IPC-Cmd protobuf-devel unzip valgrind valgrind-devel zlib-devel

macOS

# 需先安装Xcode Command Line Tools
xcode-select --install
brew install libyaml

源码构建与开发环境激活

# 克隆代码仓库
git clone https://gitcode.com/gh_mirrors/kon/kong
cd kong

# 设置GitHub访问令牌（用于依赖下载）
export GITHUB_TOKEN=ghp_xxxxxx_your_access_token

# 构建开发环境
make build-venv

# 激活开发环境（Bash/Zsh）
. bazel-bin/build/kong-dev-venv.sh

# 启动依赖服务（数据库等）
start_services

# 验证Kong启动
kong start
kong health

完整的环境配置细节可参考官方开发文档：DEVELOPER.md

插件架构深度解析

Kong插件基于Lua编写，遵循OpenResty的请求处理生命周期。一个标准的Kong插件包含以下核心组件：

kong/plugins/your-plugin/
├── handler.lua      # 核心处理逻辑
├── schema.lua       # 配置验证规则
├── migrations/      # 数据库迁移脚本
└── api.lua          # 可选Admin API扩展

插件生命周期与钩子函数

Kong插件通过钩子函数介入请求处理流程，主要钩子包括：

-- handler.lua示例结构
local Plugin = {}

function Plugin:new()
  Plugin.super.new(self, "your-plugin")
end

function Plugin:access(conf)
  -- 请求转发前处理（认证、限流等）
end

function Plugin:header_filter(conf)
  -- 响应头处理
end

function Plugin:body_filter(conf)
  -- 响应体处理
end

function Plugin:log(conf)
  -- 请求完成日志处理
end

return Plugin

现有插件如hmac-auth和jwt提供了完整的实现参考。

从零开发你的第一个插件

让我们通过开发一个简单的"请求头注入"插件，掌握Kong插件开发的核心流程。

1. 创建插件基础结构

# 创建插件目录
mkdir -p kong/plugins/request-header-injector

# 创建核心文件
touch kong/plugins/request-header-injector/{handler.lua,schema.lua}

2. 编写配置验证规则（schema.lua）

-- kong/plugins/request-header-injector/schema.lua
local typedefs = require "kong.db.schema.typedefs"

return {
  name = "request-header-injector",
  fields = {
    { config = {
        type = "record",
        fields = {
          { headers = { 
              type = "map", 
              keys = typedefs.header_name,
              values = { type = "string" },
              required = true 
            } 
          },
        },
      },
    },
  },
}

3. 实现核心处理逻辑（handler.lua）

-- kong/plugins/request-header-injector/handler.lua
local RequestHeaderInjector = {}

RequestHeaderInjector.PRIORITY = 800  -- 优先级（0-1000）
RequestHeaderInjector.VERSION = "0.1.0"

function RequestHeaderInjector:access(conf)
  -- 注入配置的请求头
  for header_name, header_value in pairs(conf.headers) do
    kong.service.request.set_header(header_name, header_value)
  end
end

return RequestHeaderInjector

4. 本地测试插件

# 注册插件
export KONG_PLUGINS=bundled,request-header-injector

# 重启Kong
kong restart

# 通过Admin API启用插件
curl -X POST http://localhost:8001/services/{service}/plugins \
  -d "name=request-header-injector" \
  -d "config.headers.X-Inject-By=Kong-Community" \
  -d "config.headers.X-Plugin-Version=0.1.0"

代码质量与测试策略

高质量的插件需要完善的测试覆盖和代码规范遵循。Kong使用busted作为测试框架，luacheck进行静态代码分析。

单元测试编写

在spec/03-plugins/目录下创建测试文件：

-- spec/03-plugins/request-header-injector/handler_spec.lua
local busted = require "busted"
local assert = require "luassert"
local handler = require "kong.plugins.request-header-injector.handler"

describe("request-header-injector plugin", function()
  it("should inject configured headers", function()
    local conf = {
      headers = {
        ["X-Test"] = "test-value"
      }
    }
    
    -- 模拟Kong上下文
    local mock_service = {
      request = {
        set_header = function(name, value)
          assert.equal("X-Test", name)
          assert.equal("test-value", value)
        end
      }
    }
    
    _G.kong = { service = mock_service }
    
    -- 调用access钩子
    handler.access(conf)
  end)
end)

测试执行与代码检查

# 运行单元测试
make test-plugins

# 执行静态代码检查
make lint

# 完整测试套件
make test-all

测试规范详情可参考：CONTRIBUTING.md

贡献代码提交全流程

代码提交规范

Kong采用Conventional Commits规范，提交信息格式为：

<type>(<scope>): <subject>

<body>

<footer>

例如：

feat(request-header-injector): add support for dynamic values

Allow header values to reference request context using ${} syntax,
e.g. "X-Request-ID: ${request_id}".

Fixes #1234

提交PR前的检查清单

•  代码遵循Kong Lua风格指南
•  添加/更新测试用例
•  运行make lint通过静态检查
•  编写插件文档（至少包含使用示例）
•  添加变更日志（changelog/unreleased/kong/your-change.yml）

提交PR的命令流程

# 创建特性分支
git checkout -b feat/request-header-injector

# 提交更改
git add .
git commit -m "feat(request-header-injector): implement core functionality"

# 推送到远程仓库
git push origin feat/request-header-injector

然后在GitCode上创建Pull Request，遵循PR模板填写相关信息。

完整的贡献指南参见：CONTRIBUTING.md

社区贡献进阶指南

插件发布与推广

非核心插件建议通过LuaRocks发布：

# 创建rockspec文件
luarocks new_version kong-plugin-request-header-injector 0.1.0

# 上传到LuaRocks
luarocks upload kong-plugin-request-header-injector-0.1.0-1.rockspec --api-key=your-api-key

同时可以：

• 在Kong Hub注册你的插件
• 在Kong Nation发布插件介绍
• 参与Kong社区双周会分享你的插件

贡献者徽章与社区激励

成功合并PR后，你可以申请Kong贡献者徽章：

1. 填写贡献者表单
2. 在社交媒体展示你的贡献
3. 参与Kong年度贡献者评选

总结与展望

通过本文，你已掌握Kong插件开发的全流程，从环境搭建到代码提交。Kong社区欢迎各种创新插件，无论是API安全、流量管理，还是新兴的AI集成场景（如ai-proxy插件）。

作为下一代云原生API网关，Kong正积极拥抱Service Mesh、WebAssembly等技术趋势。你的每一行代码，都在塑造API基础设施的未来。立即行动，将你的创意转化为推动API生态发展的力量！

记住：最好的学习方式是实践。选择一个你感兴趣的问题领域，开始编写你的第一个Kong插件吧！

【免费下载链接】kong 🦍 The Cloud-Native API Gateway and AI Gateway. 项目地址: https://gitcode.com/gh_mirrors/kon/kong