HttpLuaModule——翻譯（Nginx API for Lua）

現在我已經將翻譯的內容放到：http://wiki.nginx.org/HttpLuaModuleZh

Nginx API for Lua

Introduction

各種各樣的*_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*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua*, ngx.timer.*

以ngx.NOTICE的日志級別寫入到nginx的error.log文件。他等價於：ngx.log(ngx.NOTICE, ...)

LUA可以接收nil參數，並且等價於字符串"nil"。同樣適用於ngx的布爾型的變量"true"和"false"。ngx.null將會以字符串"null"輸出。

NGINX有一個硬編碼的錯誤，一條日志只能在2048個字節內。如果多余這些個數，將會被截取。如果想要修改這個限制，需要修改NGINX的源代碼，位於src/core/ngx_log.h的NGX_MAX_ERROR_STR宏。