APISIX 运行时调试
0x00 说明
本文基于 APISIX 2.5,IDEA 2021.1,IntelliJ-EmmyLua 插件 1.3.6.215,MobDebug 0.709。
0x01 环境
我是在 CentOs 7 系统中进行开发的,首先搭建APISIX 开发环境,根据 APISIX 的官方文档,先安装依赖,然后通过源码包安装 APISIX。
APISIX 的安装位置是 /usr/local/apisix
,开发环境搭建完成后, cd
到 该目录下,可以通过 ./bin/apisix start
命令启动 APISIX。
在 CentOs 7 中安装 IDEA 和 Emmyua 插件的过程不赘述。
0x02 项目
用 IDEA 打开 /usr/local/apisix
,根据 EmmLua 教程,首先设置项目结构,将 /usr/local/apisix
设置为项目根目录
必须将源码的根目录设置为 Sources 目录。
具体做法是打开菜单 File -> Project Structure 打开 Project Structure 设置面板,点击右侧的 Add Content Root 来添加你的源码根目录,然后点击 Mark as Sources 标记。
设置完成后的项目结构如下
在 /usr/local/apisix
下新建 lualib
目录,下载 mobdebug.lua 代码,放在 lualib
目录中,效果如下
然后参考配置项目依赖库,把 lualib
设置为项目的 lib
,设置完成后效果如下
这里也可以在 lualib
中继续添加 emmylua_ngx.lua ,用于补充openresty函数提示专用库,方便在写代码的时候获得更多的提示。
0x03 调试
新建 Lua Remote(Mobdebug),具体过程参考:emmylua.github.io/run/remote.…
添加完成后效果如下
在需要 debug 的地方添加如下函数
require("lualib.mobdebug").start("127.0.0.1", 8172)
在 IDEA 中启动 remote debug 进程,效果如下
在 IDEA console 中会出现 debug 进程启动的消息,这相当于启动了一个进程,监听 8172 端口,这个进程属于 IDEA 的,与 APISIX 没什么关系,查看以下监听 8172 端口的进程信息
简单理解一下, debug 的过程相当于在本地启动一个进程,监听 8172 端口。当 APISIX 运行到 debug 函数的时候,让当前协程挂起,然后调用 lualib/mobdebug.lua
模块将中的功能,将当前函数相关的变量,堆栈信息通过 LuaSocket 发送到 127.0.0.1:8172,即本地的 8172 端口,监听 8172 端口的进程接受到这些信息之后,在 IDEA 中展示。
启动 APISIX,命令如下
./bin/apisix start
在这里需要注意,提前配置好 APISIX 中的 route upstream 等信息,启动 APISIX 后,构造请求,访问 APISIX,触发代码运行到需要 debug 的地方。
比如我配置的 route 如下
{
"id": "1",
"update_time": 1611044949,
"uri": "/foo/*",
"status": 1,
"priority": 0,
"plugins": {},
"upstream": {
"nodes": {
"127.0.0.1:1980": 2,
"127.0.0.1:1981": 1
},
"type": "roundrobin"
},
"create_time": 1611044129
}
在 upstream 中配置了 2 个 node,当我访问
curl 127.0.0.1:9080/foo/1
的时候,APISIX 的代码会运行到 /usr/local/apisix/apisix/balancer.lua
模块的第 230 行,即我添加 debug 函数的地方。
debug 效果如下
还可以计算表达式
可以单步调试,进入或者跳出函数。比如 230 行函数
local ok, err = balancer.set_current_peer(server.host, server.port)
调用了 set_current_peer
函数,当 debug 到这行时,按 F7 进入该函数
0x04 尾声
本文介绍的 APISIX 动态调试功能主要用于学习源码,了解其运行过程,提高学习效率。希望能帮助到和我一样,习惯了动态调试,刚开始接触 APISIX/OpenResty/Kong 等相关技术栈的小伙伴。