nginx api for lua

Nginx API for Lua Introduction
更多的api  查看  http://wiki.nginx.org/HttpLuaModuleZh

各種各樣的*_by_lua和*_by_lua_file設定檔服務在都在nginx.conf檔案內。這些LUA API只能運行在這些設定檔裡面。

這個API有兩個標準的包NGX和NDK。這個包在ngx_lua內預設的包。

這個軟體包可以這樣的引入外部的檔案

    local say = ngx.say     module(...)     function foo(a)         say(a)     end

強烈不推薦使用package.seeall標誌，這樣會引起很多意想不到的後果。

也可以直接引用LUA包：

    local ngx = require "ngx"    local ndk = require "ndk"

在我們的代碼裡面使用網路I/O操作時，最好使用LUA的API，因為NGINX是非阻塞的，如果不這樣做可能死迴圈或者導致效能的直線下降。磁碟操作的資料量相對較小，可以採用標準的Lua的IO庫，但巨大的檔案閱讀和寫作應儘可能避免。為了發揮NGINX的效能，強烈建議所有的網路和磁碟I/O操作Nginx的子請求（通過ngx.location.capture方法和類似）都不要阻塞NGINX進程。 ngx.arg

文法：val = ngx.arg[index]

環境：set_by_lua*,body_filter_by_lua*

當它運行在set_by_lua或者set_by_lua_file指令的時候，這個table是唯讀並且包括配置指令的輸入參數，例如：value = ngx.arg[n]

這裡有個例子：

    location /foo {        set $a 32;        set $b 56;         set_by_lua $res            'return tonumber(ngx.arg[1]) + tonumber(ngx.arg[2])'            $a $b;         echo $sum;    }

輸出的結果是 88

當table是根據body_filter_by_lua或body_filter_by_lua_file的上下文使用的時候，第一個元素，在過濾器的輸出代碼中儲存的輸入資料區塊和所述第二元件持有“EOF”的標誌，表示整個輸出資料流的結束的布爾標誌。

資料區塊和“EOF”標誌傳遞給下遊的Nginx的輸出濾波器，直接對應的表元素賦值，也可以覆蓋。當設定為零或空的Lua字串值ngx.arg的[1]，沒有資料區塊會被傳遞給所有的下遊的Nginx的輸出濾波器。 ngx.var.VARIABLE

文法：ngx.var.var_name

語境：set_by_lua*,rewrite_by_lua*,access_by_lua...

讀寫NGNIX變數。

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

不僅僅可以讀，也可以寫，例如： 

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

當然，NGNIX不能憑空被添加。一些特殊的NGINX變數，比如$args和$limit_rate能夠被賦值，有些不能，比如$arg_PARAMETER。

給ngx.var.Foo一個nil，將會取消NGINX的$Foo變數。

警告：當從nginx讀取變數，NGINX會給每一個請求的記憶體池分配記憶體，他在記憶體終止的時候會釋放出來，所以當你需要讀取NGINX變數的時候，你的LUA變數會緩衝NGINX變數，例如：

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

防止臨時請求請求周期內的記憶體流失。 Core constants

環境：init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, *log_by_lua*, ngx.timer.*

  ngx.OK (0)  ngx.ERROR (-1)  ngx.AGAIN (-2)  ngx.DONE (-4)  ngx.DECLINED (-5)

 

注意：只有三種常量被NGNIX LUA使用（ngx.exit()只接收 NGX_OK, NGX_ERROR, 和NGX_DECLINED）

ngx.null是NULL，在LUA中是nil，類似於lua-cjson的cjson.null。 HTTP method constants

環境：init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua*, ngx.timer.*

  ngx.HTTP_GET  ngx.HTTP_HEAD  ngx.HTTP_PUT  ngx.HTTP_POST  ngx.HTTP_DELETE  ngx.HTTP_OPTIONS   (added in the v0.5.0rc24 release)  ngx.HTTP_MKCOL     (added in the v0.8.2 release)  ngx.HTTP_COPY      (added in the v0.8.2 release)  ngx.HTTP_MOVE      (added in the v0.8.2 release)  ngx.HTTP_PROPFIND  (added in the v0.8.2 release)  ngx.HTTP_PROPPATCH (added in the v0.8.2 release)  ngx.HTTP_LOCK      (added in the v0.8.2 release)  ngx.HTTP_UNLOCK    (added in the v0.8.2 release)  ngx.HTTP_PATCH     (added in the v0.8.2 release)  ngx.HTTP_TRACE     (added in the v0.8.2 release) 

這些變數經常在ngx.location.capture 或者 ngx.location.capture_multi方法中被調用 HTTP status constants

環境：init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua*, ngx.timer.*

  value = ngx.HTTP_OK (200)  value = ngx.HTTP_CREATED (201)  value = ngx.HTTP_SPECIAL_RESPONSE (300)  value = ngx.HTTP_MOVED_PERMANENTLY (301)  value = ngx.HTTP_MOVED_TEMPORARILY (302)  value = ngx.HTTP_SEE_OTHER (303)  value = ngx.HTTP_NOT_MODIFIED (304)  value = ngx.HTTP_BAD_REQUEST (400)  value = ngx.HTTP_UNAUTHORIZED (401)  value = ngx.HTTP_FORBIDDEN (403)  value = ngx.HTTP_NOT_FOUND (404)  value = ngx.HTTP_NOT_ALLOWED (405)  value = ngx.HTTP_GONE (410)  value = ngx.HTTP_INTERNAL_SERVER_ERROR (500)  value = ngx.HTTP_METHOD_NOT_IMPLEMENTED (501)  value = ngx.HTTP_SERVICE_UNAVAILABLE (503)  value = ngx.HTTP_GATEWAY_TIMEOUT (504) (first added in the v0.3.1rc38 release)

Nginx log level constants

  ngx.STDERR  ngx.EMERG  ngx.ALERT  ngx.CRIT  ngx.ERR  ngx.WARN  ngx.NOTICE  ngx.INFO  ngx.DEBUG

print

文法：print(...)

環境：init_by_lua*, set_by_lua*, rewri