KONG專題目錄

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模塊來定義的.

劃重點: 在生產中, 我們一般是希望在收到客戶端請求后, 轉發給后端服務處理前 做點什么 , 所以, 這個時候 access() 方法里, 是我們添加插件功能的最佳場所.
另外, 如果需要在返回給用戶的結果上做些過濾處理, 那么可以考慮在header_filter(),body_filter()中做些文章.

說到這里, 小伙伴們, 是不是覺得還是有點虛? 說了半天, 畢竟我們還是不知道如何讀寫那些個請求的信息呀. Kong系統大概會提供一些現成的參數給我們直接使用吧?

巧的很, kong官方提供了一套Plugin Development Kit給我們使用. 一聽SDK, 是不是很容易聯想到要一堆配置,引包啥的騷(復雜)操作? 小伙伴們多心了.在我們的代碼中, 可以直接使用PDK里的變量.
那么下面就介紹一下PDK提供的一些便利的操作:

劃重點:

• 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, 臺風過境,心無波瀾,又是美的一天, 哈哈

KONG專題目錄