Kong[nginx]-11 插件开发入门

TL;NR

这是一篇真正编写Kong插件的文章(お待たせしました😅)

本文通过一个自定义插件的编写,来进一步分析和学习Kong的插件机制以及开发注意点.
插件功能:

• 分析请求的header参数,编写请求校验功能
• 在向后端接口转发请求之前,添加header参数
• 向端处理结果在向用户返回之前, 添加header参数

0x01 准备篇

本文假设小伙伴们已经全部了解了前面 10 篇文章的内容.
尤其是上一篇,关于Kong自定义插件的部署过程.

代码准备: 这一篇我们编写一个普通的SpringBoot工程(Web),提供的业务功能很简单, 就是向客户端打印请求(header,body)参数.

主要代码如下:

@RestController
@SpringBootApplication
public class UserApplication {

   public static void main(String[] args) {
       SpringApplication.run(UserApplication.class, args);
   }

   @RequestMapping(value = "/v1/user/get", produces = "application/json")
   public String hello(HttpServletRequest req, @Nullable @RequestBody String body) {

       JSONObject obj = new JSONObject();
       obj.put("msg", "Hi, man");
       JSONObject header = new JSONObject();
       Enumeration<String> headerNames = req.getHeaderNames();
       while (headerNames.hasMoreElements()) {
           String name = headerNames.nextElement();
           header.put(name, req.getHeader(name));
       }

       obj.put("header", header);
       obj.put("body", JSON.parse(body));
       return JSON.toJSONString(obj);
   }
}

0x02 插件机制

上一篇我们学习到, 一个插件必需包含两个文件

• handler.lua 主要负责业务功能编写
  我们可以想到,插件功能的开发, 一般都是基于一些固定的接口.
  在运行的时候, 系统会根据接口规范调用相关的方法,进而完成插件的处理流程.
  Kong也不例外, 在Kong中, 我们可以通过继承一个base插件:
  kong.plugins.base_plugin.
  这个base插件提供了一些方法待实现, 这些方法是基于 openresty的http模块来定义的.

方法名	功能及触发时机
init_worker()	每次nginx worker 进程起来的时候执行
certificate()	SSL请求时, 在SSL握手时执行
rewrite()	这个方法只能在全局插件时才可能被使用
access()	收到客户端请求,转向上流服务之前执行
header_filter()	上流服务处理完成后,返回给客户端之前
body_filter()	上流服务处理完成后,返回给客户端之前
log()	返回给客户端完成后执行

划重点: 在生产中, 我们一般是希望在收到客户端请求后, 转发给后端服务处理前 做点什么 , 所以, 这个时候 access() 方法里, 是我们添加插件功能的最佳场所.
另外, 如果需要在返回给用户的结果上做些过滤处理, 那么可以考虑在header_filter(),body_filter()中做些文章.

说到这里, 小伙伴们, 是不是觉得还是有点虚? 说了半天, 毕竟我们还是不知道如何读写那些个请求的信息呀. Kong系统大概会提供一些现成的参数给我们直接使用吧?

巧的很, kong官方提供了一套Plugin Development Kit给我们使用. 一听SDK, 是不是很容易联想到要一堆配置,引包啥的骚(复杂)操作? 小伙伴们多心了.在我们的代码中, 可以直接使用PDK里的变量.
那么下面就介绍一下PDK提供的一些便利的操作:

PDK名称	功能描述
kong.client	提供客户端的ip, 端口等信息
kong.ctx	提供了插件之间共享并传递参数的桥梁
kong.ip	提供了kong.ip.is_trusted(address)IP白名单检测方法
kong.log	日志方法
kong.node	返回此插件的UUID信息
kong.request	仅提供request信息的读取功能,access()中可读
kong.response	提供response信息的读写功能, access()中不可用
kong.router	返回此请求关联的router信息
kong.service	返回此请求关联的service,可以动态修改后端服务信息
kong.service.request	仅用于access()方法中,可以读写请求信息
kong.service.response	仅可用于header_filter(), body_filter()方法中,只提供header信息的读取功能
kong.table	kong提供的一套数据结构功能

划重点:

• kong.service.request : 可以在access()中修改参数
• kong.response: 可以header_filter()中修改返回结果
• kong.log("aaa"): 打印普通日志
• kong.log.inspect(some_val) : 可以递归打印 table 等复杂数据结果

• schema.lua 主要负责插件参数的定制
  小伙伴们肯定还记得, 我们在之前的文章中,在配置插件时, 经常要输入一些字符串常量, 有些必需要按回车才能生效.
  这些操作需求呢,就是由 schema.lua来定义的.
  在schema.lua中, 会返回一个lua的字典, 下文会看到代码介绍.

0x03 插件代码

• handler.lua:

-- handler.lua
local BasePlugin   = require "kong.plugins.base_plugin"

local JSHandler    = BasePlugin:extend()

JSHandler.VERSION  = "1.0.0"
JSHandler.PRIORITY = 10

function JSHandler:new()
    JSHandler.super.new(self, "jian-shu-plugin")
end

function JSHandler:init_worker()
    JSHandler.super.init_worker(self)
end

function JSHandler:preread(config)
    JSHandler.super.preread(self)
end

function JSHandler:certificate(config)
    JSHandler.super.certificate(self)
end

function JSHandler:rewrite(config)
    JSHandler.super.rewrite(self)
end

function JSHandler:access(config)
    JSHandler.super.access(self)
    -- 如果Header中不包含kong字段, 提示出错
    if kong.request.get_header("kong") == nil then
        return kong.response.exit(403, "Access Forbidden, Show me the code!!!", {
            ["Content-Type"] = "text/plain",
            ["WWW-Authenticate"] = "Basic"
        })
    end
    -- 增加请求参数,设置常量
    kong.service.request.add_header("value_1", "Add by plugin")
    -- 增加请求参数,设置插件参数
    kong.service.request.add_header("value_2", config.username[1])
    -- 打印日志位置: /usr/local/kong/logs/error.log
    kong.log.inspect(config.username)
end

function JSHandler:header_filter(config)
    JSHandler.super.header_filter(self)
    -- 向客户端返回时, 添加header参数
    kong.response.set_header("author", "JianShuWeb")
end

function JSHandler:body_filter(config)
    JSHandler.super.body_filter(self)
end

function JSHandler:log(config)
    JSHandler.super.log(self)
end

return JSHandler

可以看到, 主要内容就是实现一个BasePlugin:extend(),实现一系统生命周期对应的方法后,返回这个实例即可.
而且, 所有方法在实现的时候, 都要先调用一下父类方法.

关于代码的说明 ,已经写在注释里了. 理解起来是不是很简单 :-)

• schema.lua

local typedefs     = require "kong.db.schema.typedefs"
-- 定义输入类型为 字符串 数组, 意为可以输入多个字符串
local string_array = {
    type     = "array",
    default  = {},
    elements = { type = "string" },
}

return {
    name   = "jian-shu",
    fields = {
        { protocols = typedefs.protocols_http },
        { config = {
            type   = "record",
            fields = {
                -- 这里的username, 会显示在插件配置页
                { username = string_array },
            },
        },
        },
    },
}

这里, 应该是最低配置的插件说明了. 关于schema的高级用法请参数这里.

0x04 部署

• 先把代码放置到/opt/share/kong/plugins/jianshu位置
  插件代码位置
• 修改/etc/kong/kong.conf文件,加载插件

lua_package_path = /opt/share/?.lua;;
plugins = bundled,jianshu

• 重启Kong服务: kong restart

0x05 验证

• 打开konga首页,插件加载情况:

  
  加载成功

• 添加插件:
  在我们已有的Router上,增加本插件

  
  添加插件

• 配置参数:
  输入插件参数, 并回车, 最后提交.

  
  配置参数

• 不带kongheader参数请求:
  由于header参数中, 没有 kong 字段, 所以我们插件生效后, 返回403
  

  失败例

• 带kong参数请求:
  这一次添加kong参数,可以正常返回 , 而且在返回的结果中, 我们也可以看到:在function JSHandler:access(config)方法中动态添加的两个字段, 也完美的传递给了后端服务.
  

  正常返回

到此, 今天的实践内容顺利结束 😆

0x06 后记

今天的内容,完美诠释了, 什么叫做 API网关 操作.
那么,基于今天的内容,我们可以做些什么骚操作呢?

• 结合URL,HEADER参数,自定义请求校验逻辑.
• 动态修改线上服务的运行参数(临时打开debug日志)
• 有个大胆的想法: 不需要后端,直接在插件里做简单业务逻辑开发 ??

PS, 台风过境,心无波澜,又是美的一天, 哈哈