【重要】Nginx模块之————Lua的Nginx API 常量以及参数介绍 (Lua-Nginx-Module 模块)

一、介绍

　　各种* _by_lua，* _by_lua_block和* _by_lua_file配置指令用作nginx.conf文件中Lua API的网关。 下面描述的Nginx Lua API只能在这些配置指令的上下文中运行的用户Lua代码中调用。API以两个标准软件包ngx和ndk的形式暴露给Lua。 这些软件包位于ngx_lua中的默认全局范围内，并且始终可在ngx_lua指令中使用。

这些包可以像这样引入外部Lua模块：

 local say = ngx.say
 local _M = {}
 function _M.foo(a)
     say(a)
 end
 return _M

强烈建议使用package.seeall标志，因为其各种不良的副作用。也可以直接要求外部Lua模块中的包：

  local ngx = require“ngx”
  local ndk = require“ndk”

　　v0.2.1rc19版本中引入了需要这些软件包的能力。

　　用户代码中的网络I / O操作应该只通过Nginx Lua API调用来完成，因为Nginx事件循环可能被阻塞，否则性能会明显下降。 磁盘操作与相对少量的数据可以使用标准的Lua io库，但巨大的文件读写应尽可能避免，因为他们可能会显着阻止Nginx进程。 强烈建议将所有网络和磁盘I / O操作委派给Nginx的子请求（通过ngx.location.capture方法等），以获得最佳性能。

二、命令介绍

ngx.arg

语法：val = ngx.arg [index]

上下文：set_by_lua *，body_filter_by_lua *

描述：当在set_by_lua *指令的上下文中使用时，此表是只读的，并保存config指令的输入参数：

value = ngx.arg[n]

这里是一个例子

　　　　location /foo_sum {
                 set $a 32;
                 set $b 56;
                 set_by_lua $sum
                        ‘return tonumber(ngx.arg[1]) + tonumber(ngx.arg[2])‘
                 $a $b;
                 echo "sum = ${sum}";
        }

CURL 运行输出

root@iZ236j3sofdZ:/usr/local/nginx/conf/lua# curl "http://localhost/foo_sum"
sum = 88

写出88，32和56的和。

　　当在body_filter_by_lua *的上下文中使用此表时，第一个元素将输入数据块保存到输出过滤器代码，第二个元素保存指示整个输出数据流结束的“eof”标志的布尔标志。

　　传递给下游Nginx输出过滤器的数据块和“eof”标志也可以通过将值直接分配给相应的表元素来覆盖。 当将nil或空Lua字符串值设置为ngx.arg [1]时，根本不会将数据块传递到下游Nginx输出过滤器。

ngx.null

　　ngx.null常量是一个NULL light用户数据，通常用于在Lua表等中表示nil值，类似于lua-cjson库的cjson.null常量。 这个常数首先在v0.5.0rc5版本中引入。

ngx.var.VARIABLE 

语法：ngx.var.VAR_NAME

上下文：set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*

读取和写入Nginx变量值

 value = ngx.var.some_nginx_variable_name
 ngx.var.some_nginx_variable_name = value

注意，只有已经定义的nginx变量可以写入。 例如：

location /foo {
     set $my_var ‘‘; # this line is required to create $my_var at config time
     content_by_lua_block {
         ngx.var.my_var = 123;
         ...
     }
 }

也就是说，nginx变量不能在运行中创建。一些特殊的nginx变量，如$ args和$ limit_rate可以分配一个值，许多其他变量不是，如$ query_string，$ arg_PARAMETER和$ http_NAME。通过写入ngx.var [1]，ngx.var [2]，ngx.var [3]等，也可以通过此接口读取Nginx正则表达式组捕获变量$ 1，$ 2，$ 3等。将ngx.var.Foo设置为nil值将取消设置$ Foo Nginx变量。

ngx.var.args = nil

小心当从Nginx变量读取时，Nginx将在每个请求的内存池中分配内存，只有在请求终止时才释放内存。 因此，当您需要在Lua代码中重复读取Nginx变量时，将Nginx变量值缓存到您自己的Lua变量中，例如：

local val = ngx.var.some_var
 --- use the val repeatedly later

以防止（临时）内存在当前请求的生存期内泄漏。 缓存结果的另一种方法是使用ngx.ctx表。未定义的NGINX变量评估为nil，而未初始化（但已定义）的NGINX变量将被评估为空的Lua字符串。此API需要相对昂贵的元方法调用，建议避免在热代码路径上使用它。

待续.........