ngx_lua模块API 浅析

【本想把英文翻译过来，发现有人已经翻译了，杯具。我就不做无用功了。】

附中文wiki链接：

点击打开链接

lua_use_default_type 

语法: lua_use_default_type on | off

默认值: lua_use_default_type on

配置段: http, server, location, location if

是否使用 MIME type（

MIME (Multipurpose Internet Mail Extensions) 是描述消息内容类型的因特网标准。

MIME 消息能包含文本、图像、音频、视频以及其他应用程序专用的数据。

参考：http://www.w3school.com.cn/media/media_mimeref.asp）

对响应头Content-Type进行赋值

默认打开。

lua_code_cache on | off;

作用:打开或关闭 Lua 代码缓存，影响以下指令： set_by_lua_file , content_by_lua_file, rewrite_by_lua_file, access_by_lua_file 及强制加载或者reload Lua 模块等.缓存开启时修改LUA代码需要重启nginx,不开启时则不用。

开发阶段一般关闭缓存。这样的话每次修改代码后，不用reload nginx 即可生效。

作用域：main, server, location, location if

lua_regex_cache_max_entries 1024;

语法: lua_regex_cache_max_entries <num>

默认值: lua_regex_cache_max_entries 1024

配置段: http

指定worker进程中的正则表达式缓存条目允许的最大数量。默认为1024.

如果正则选项 o  被置位的话， ngx.re.match, ngx.re.gmatch, ngx.re.sub, 和 ngx.re.gsub  中的正则表达式将会被缓存在这里。

当超出1024时，新的正则表达式将不会被缓存，就好像 o 选项没有被指定，而且会在error.log中留下一条，且仅有一条日志

2011/08/27 23:18:26 [warn] 31997#0: *1 lua exceeding regex cache max entries (1024), ...

请不要使能 o 选项以避免触及指定的限制。

lua_regex_match_limit

语法: lua_regex_match_limit <num>

默认值: lua_regex_match_limit 0

配置段: http

 当执行 ngx.re API时，指定 PCRE 库使用的匹配上限 

当触发限制时，ngx.re API 将会返回 错误信息  "pcre_exec() failed: -8" .

当配置为零时，编译PCRE时将使用默认的匹配限制，这也是这条指令的默认值。

lua_package_path

语法: lua_package_path <lua-style-path-str>

默认值: 环境变量 LUA_PATH 的值 或者 Lua 默认编译路径.

配置段: http

设定lua代码的默认搜索路径。标准lua 路径格式，可以使用;;表示初始搜索路径

lua_package_cpath

语法: lua_package_cpath <lua-style-cpath-str>

默认值: 环境变量 LUA_PATH 的值 或者 Lua 默认编译路径.

配置段: http

设定lua C 模块的默认搜索路径。标准lua C 路径格式，可以使用;; 表示初始搜索路径

例子：

lua_package_cpath '/bar/baz/?.so;/blah/blah/?.so;;';

init_by_lua

语法: init_by_lua <lua-script-str>

配置段: http

处理阶段: loading-config

在nginx master 进程 加载nginx 配置文件的时候，运行lua脚本路径中的lua代码。

当nginx收到HUP 信号并且开始reload 配置文件，lua 虚拟机会被重新创建，init_by_lua也会在新的lua 虚拟机中重新运行。如果 lua_code_cache 指令是关闭的，init_by_lua将会运行在每一个请求之上，因为在这种特殊场景下，每一个请求都会新建一个lua虚拟机。

一般，你可以通过这个指令，寄存lua全局变量或者预加载lua模块。例如：

init_by_lua 'cjson = require "cjson"';   --预加载cjson 模块

server {
    location = /api {
        content_by_lua '
            ngx.say(cjson.encode({dog = 5, cat = 6}))
        ';
    }
}

你也可以初始化lua 共享内存

lua_shared_dict dogs 1m;

init_by_lua '
    local dogs = ngx.shared.dogs;
    dogs:set("Tom", 56)
';

server {
    location = /api {
        content_by_lua '
            local dogs = ngx.shared.dogs;
            ngx.say(dogs:get("Tom"))
        ';
    }
}

但是请注意的是，lua 共享内存的存储空间在reload 之后不会被清理。（比如通过hup 信号）

所以如果你不想重新初始化共享内存，你需要设置一个用户标记位并不断在代码当中检查它。

因为在这个阶段，lua 代码运行在nginx fork 它的 worker 进程之前，数据和代码会共享操作系统提供的 Copy-on-write (COW)特性 （详见：https://en.wikipedia.org/wiki/Copy-on-write） 没这样可以节约很多内存空间。

不要在这里初始化自己的Lua全局变量，因为在这种情况下使用Lua全局变量有性能损失，并可能导致全局命名空间污染（更多细节见见lua变量范围 Lua Variable Scope 部分）。推荐的方法是使用适当的Lua模块文件（但不使用标准Lua函数module()定义Lua模块，因为它也会污染全局命名空间）和调用require()在init_by_lua或其他阶段加载自己的模块文件（由于require() 会在 package.loaded表中并加载并缓存lua模块， 所以在整个Lua虚拟机实例中你的模块只会加载一次）。

本阶段仅支持很少的 Nginx API for Lua

• 日志相关 APIs: ngx.log and print,
• 共享内存 API: ngx.shared.DICT.

你应该非常小心你的LUA代码潜在的安全漏洞，因为nginx的主进程通常运行在root帐户下。

init_by_lua_file

语法: init_by_lua_file <path-to-lua-script-file>

配置段: http

生效阶段: loading-config

类似于init_by_lua  

当指定的为相对路径是，会根据环境变量自动扩展为绝对路径。

init_worker_by_lua

语法: init_worker_by_lua <lua-script-str>

配置段: http

生效阶段: starting-worker

当master 使能的时候，在每一个worker 进程启动阶段运行运行lua 代码 。

在master 去使能的时候，这个钩子仅会运行在 init_by_lua*.  之后。

这个钩子通常用来创建重复定时器，或用来做后端健康检查等日常工作。下面是一个例子：

init_worker_by_lua '
    local delay = 3  -- in seconds
    local new_timer = ngx.timer.at
    local log = ngx.log
    local ERR = ngx.ERR
    local check

    check = function(premature)
        if not premature then
            -- do the health check or other routine work
            local ok, err = new_timer(delay, check)
            if not ok then
                log(ERR, "failed to create timer: ", err)
                return
            end
        end
    end

    local ok, err = new_timer(delay, check)
    if not ok then
        log(ERR, "failed to create timer: ", err)
        return
    end
';

set_by_lua $var '<lua-script>' [$arg1 $arg2];
set_by_lua_file $var <path-to-lua-script-file> [$arg1 $arg2 ...];
作用：设置一个Nginx变量，变量值从lua脚本里运算由return返回，可以实现复杂的赋值逻辑；此处是阻塞的，Lua代码要做到非常快.
另外可以将已有的ngx变量当作参数传进Lua脚本里去，由ngx.arg[1],ngx.arg[2]等方式访问。
作用域：main, server, location, server if, location if
处理阶段：rewrite

content_by_lua '<lua script>';
content_by_lua_file luafile;
作用域：location, location if
说明：内容处理器，接收请求处理并输出响应，content_by_lua直接在nginx配置文件里编写较短Lua代码后者使用lua文件。

rewrite_by_lua '<lua script>'
rewrite_by_lua_file lua_file;
作用域：http, server, location, location if
执行内部URL重写或者外部重定向，典型的如伪静态化的URL重写。其默认执行在rewrite处理阶段的最后.
注意，在使用rewrite_by_lua时，开启rewrite_log on;后也看不到相应的rewrite log。

access_by_lua 'lua code';
access_by_lua_file lua_file.lua;
作用：用于访问控制，比如我们只允许内网ip访问，可以使用如下形式。
access_by_lua '
if ngx.req.get_uri_args()["token"] ~= "123" then  
  return ngx.exit(403)  
end ';
作用域：http, server, location, location if

header_filter_by_lua 'lua code';
header_filter_by_lua_file path_file.lua;
作用：设置header 和 cookie；

lua_need_request_body on|off;
作用：是否读请求体，跟ngx.req.read_body()函数作用类似,但官方不推荐使用此方法。

lua_shared_dict shared_data 10m;
作用：设置一个共享全局变量表，在所有worker进程间共享。在lua脚本中可以如下访问它：
例：local shared_data = ngx.shared.shared_data 
10m 是共享内存的大小。

init_by_lua 'lua code';
init_by_lua_file lua_file.lua;
作用域：http
说明：ginx Master进程加载配置时执行；通常用于初始化全局配置/预加载Lua模块

init_worker_by_lua 'lua code';
init_worker_by_lua_file luafile.lua;
作用域：http

说明：每个Nginx Worker进程启动时调用的计时器，如果Master进程不允许则只会在init_by_lua之后调用；通常用于定时拉取配置/数据，或者后端服务的健康检查。

方法和常量 

ngx.arg[index]  #ngx指令参数，当这个变量在set_by_lua或者set_by_lua_file内使用的时候是只读的，指的是在配置指令输入的参数.
ngx.var.varname   #读写NGINX变量的值,最好在lua脚本里缓存变量值，避免在当前请求的生命周期内内存的泄漏
ngx.config.ngx_lua_version #当前ngx_lua模块版本号
ngx.config.nginx_version #nginx版本
ngx.worker.exiting #当前worker进程是否正在关闭
ngx.worker.pid #当前worker进程的PID
ngx.config.nginx_configure #编译时的./configure命令选项
ngx.config.prefix #编译时的prefix选项


core constans: #ngx_lua 核心常量
ngx.OK (0)
ngx.ERROR (-1)
ngx.AGAIN (-2)
ngx.DONE (-4)
ngx.DECLINED (-5)
ngx.nil
http method constans: #经常在ngx.location.catpure和ngx.location.capture_multi方法中被调用.
ngx.HTTP_GET
ngx.HTTP_HEAD
ngx.HTTP_PUT
ngx.HTTP_POST
ngx.HTTP_DELETE
ngx.HTTP_OPTIONS  
ngx.HTTP_MKCOL    
ngx.HTTP_COPY      
ngx.HTTP_MOVE     
ngx.HTTP_PROPFIND 
ngx.HTTP_PROPPATCH 
ngx.HTTP_LOCK 
ngx.HTTP_UNLOCK    
ngx.HTTP_PATCH   
ngx.HTTP_TRACE  
http status constans: #http请求状态常量 
ngx.HTTP_OK (200)
ngx.HTTP_CREATED (201)
ngx.HTTP_SPECIAL_RESPONSE (300)
ngx.HTTP_MOVED_PERMANENTLY (301)
ngx.HTTP_MOVED_TEMPORARILY (302)
ngx.HTTP_SEE_OTHER (303)
ngx.HTTP_NOT_MODIFIED (304)
ngx.HTTP_BAD_REQUEST (400)
ngx.HTTP_UNAUTHORIZED (401)
ngx.HTTP_FORBIDDEN (403)
ngx.HTTP_NOT_FOUND (404)
ngx.HTTP_NOT_ALLOWED (405)
ngx.HTTP_GONE (410)
ngx.HTTP_INTERNAL_SERVER_ERROR (500)
ngx.HTTP_METHOD_NOT_IMPLEMENTED (501)
ngx.HTTP_SERVICE_UNAVAILABLE (503)
ngx.HTTP_GATEWAY_TIMEOUT (504) 


Nginx log level constants： #错误日志级别常量 ,这些参数经常在ngx.log方法中被使用.
ngx.STDERR
ngx.EMERG
ngx.ALERT
ngx.CRIT
ngx.ERR
ngx.WARN
ngx.NOTICE
ngx.INFO
ngx.DEBUG


##################
#API中的方法：
##################
print() #与 ngx.print()方法有区别，print() 相当于ngx.log()
ngx.ctx #这是一个lua的table，用于保存ngx上下文的变量，在整个请求的生命周期内都有效,详细参考官方
ngx.location.capture() #发出一个子请求，详细用法参考官方文档。
ngx.location.capture_multi() #发出多个子请求，详细用法参考官方文档。
ngx.status #读或者写当前请求的相应状态. 必须在输出相应头之前被调用.
ngx.header.HEADER #访问或设置http header头信息，详细参考官方文档。
ngx.req.set_uri() #设置当前请求的URI,详细参考官方文档
ngx.set_uri_args(args) #根据args参数重新定义当前请求的URI参数.
ngx.req.get_uri_args() #返回一个LUA TABLE，包含当前请求的全部的URL参数
ngx.req.get_post_args() #返回一个LUA TABLE，包括所有当前请求的POST参数
ngx.req.get_headers() #返回一个包含当前请求头信息的lua table.
ngx.req.set_header() #设置当前请求头header某字段值.当前请求的子请求不会受到影响.
ngx.req.read_body() #在不阻塞ngnix其他事件的情况下同步读取客户端的body信息.[详细]
ngx.req.discard_body() #明确丢弃客户端请求的body
ngx.req.get_body_data() #以字符串的形式获得客户端的请求body内容
ngx.req.get_body_file()   #当发送文件请求的时候，获得文件的名字
ngx.req.set_body_data() #设置客户端请求的BODY
ngx.req.set_body_file() #通过filename来指定当前请求的file data。
ngx.req.clear_header() #清求某个请求头
ngx.exec(uri,args) #执行内部跳转，根据uri和请求参数
ngx.redirect(uri, status) #执行301或者302的重定向。
ngx.send_headers() #发送指定的响应头
ngx.headers_sent #判断头部是否发送给客户端ngx.headers_sent=true
ngx.print(str) #发送给客户端的响应页面
ngx.say() #作用类似ngx.print，不过say方法输出后会换行
ngx.log(log.level,...) #写入nginx日志
ngx.flush() #将缓冲区内容输出到页面（刷新响应）
ngx.exit(http-status) #结束请求并输出状态码
ngx.eof() #明确指定关闭结束输出流
ngx.escape_uri() #URI编码(本函数对逗号,不编码，而php的urlencode会编码)
ngx.unescape_uri() #uri解码
ngx.encode_args(table) #将tabel解析成url参数
ngx.decode_args(uri) #将参数字符串编码为一个table
ngx.encode_base64(str) #BASE64编码
ngx.decode_base64(str) #BASE64解码
ngx.crc32_short(str) #字符串的crs32_short哈希
ngx.crc32_long(str) #字符串的crs32_long哈希
ngx.hmac_sha1(str) #字符串的hmac_sha1哈希
ngx.md5(str) #返回16进制MD5
ngx.md5_bin(str) #返回2进制MD5
ngx.today() #返回当前日期yyyy-mm-dd
ngx.time() #返回当前时间戳
ngx.now() #返回当前时间
ngx.update_time() #刷新后返回
ngx.localtime() #返回 yyyy-mm-dd hh:ii:ss
ngx.utctime() #返回yyyy-mm-dd hh:ii:ss格式的utc时间
ngx.cookie_time(sec) #返回用于COOKIE使用的时间
ngx.http_time(sec) #返回可用于http header使用的时间
ngx.parse_http_time(str) #解析HTTP头的时间
ngx.is_subrequest #是否子请求（值为 true or false）
ngx.re.match(subject,regex,options,ctx)   #ngx正则表达式匹配，详细参考官网
ngx.re.gmatch(subject,regex,opt) #全局正则匹配
ngx.re.sub(sub,reg,opt) #匹配和替换（未知）
ngx.re.gsub() #未知
ngx.shared.DICT #ngx.shared.DICT是一个table 里面存储了所有的全局内存共享变量
ngx.shared.DICT.get 
ngx.shared.DICT.get_stale 
ngx.shared.DICT.set 
ngx.shared.DICT.safe_set 
ngx.shared.DICT.add 
ngx.shared.DICT.safe_add 
ngx.shared.DICT.replace 
ngx.shared.DICT.delete 
ngx.shared.DICT.incr 
ngx.shared.DICT.flush_all 
ngx.shared.DICT.flush_expired 
ngx.shared.DICT.get_keys
ndk.set_var.DIRECTIVE #