目录

如何快速学习OpenResty的API

学会使用官方文档查询信息非常重要, 下面我们以OpenResty的ngx.arg这个API来演示如何快速学习并使用OpenResty的api.

方法1:查看lua-nginx-module官方文档

https://github.com/openresty/lua-nginx-module#nginx-api-for-lua

ngx.arg部分的截图:

../../imgs/ngx_arg_api.jpg

方法2:通过OpenResty提供的CLI(command line interface)工具"restydoc"

1
restydoc -s ngx.arg

输出如下(输出的内容和方法1的官方文档一模一样):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
ngx.arg
       syntax: val = ngx.arg[index]

       context: set_by_lua*, body_filter_by_lua*

       When this is used in the context of the set_by_lua* directives, this
       table is read-only and holds the input arguments to the config
       directives:

            value = ngx.arg[n]

       Here is an example

            location /foo {
                set $a 32;
                set $b 56;

                set_by_lua $sum
                    'return tonumber(ngx.arg[1]) + tonumber(ngx.arg[2])'
                    $a $b;

                echo $sum;
            }

       that writes out 88, the sum of 32 and 56.

       When this table is used in the context of body_filter_by_lua*, the
       first element holds the input data chunk to the output filter code and
       the second element holds the boolean flag for the "eof" flag indicating
       the end of the whole output data stream.

       The data chunk and "eof" flag passed to the downstream Nginx output
       filters can also be overridden by assigning values directly to the
       corresponding table elements. When setting "nil" or an empty Lua string
       value to "ngx.arg[1]", no data chunk will be passed to the downstream
       Nginx output filters at all.

方法3: 通过lua-nginx-module提供的测试案例学习api

https://github.com/openresty/lua-nginx-module/tree/master/t

我们可以把lua-nginx-module通过git clone到本地服务器, 然后通过grep -rl ngx.arg t/来找哪些测试案例文件里有关于这个api的内容.

总结

我们可以把以上方法中涉及到的测试案例代码粘贴到自己的测试环境中进行测试, 体会其中的意思.

通过文档和测试, 我们可知:

ngx.arg可以用于两个阶段: set_by_lua*, body_filter_by_lua*

用于body_filter阶段时: local chunk, eof = ngx.arg[1], ngx.arg[2]

ngx.arg[1]表示body里的一行数据;

ngx.arg[2]是一个布尔值, falsetrue, 如果有数据, 则为false, 如果无数据(或body尾部), 则为ture.