openresty 常用API学习一

ngx.exit
函数原型: ngx.exit(status)
函数说明: 中断当前请求，并将status返回给nginx

 

ngx.worker.exiting
函数原型：boolean = ngx.worker.exiting()
函数说明: 此函数返回一个布尔值，指示当前Nginx工作进程是否已开始退出。Nginx worker进程退出发生在Nginx server quit或configuration reload
（也称为HUP reload）上。

 

ngx.timer.at
函数原型：hdl, err = ngx.timer.at(delay, callback, user_arg1, user_arg2, ...)
函数说明: 创建带有用户回调函数和可选用户参数的Nginx计时器
第一个参数delay指定计时器的延迟（秒）。在这里可以指定0.001这样的小数秒为1毫秒。也可以指定0延迟，
    在这种情况下，当当前处理程序产生执行时，计时器将立即过期。
第二个参数callback可以是任何Lua函数，稍后将在指定延迟后的后台“light thread”中调用该函数。
    Nginx核心将使用参数premature、user_arg1、user_arg2等自动调用用户回调，其中premature参数接受一个布尔值，该值指示是否是过早计时器过期，
    user_arg1、user_arg2等是调用时指定的（额外的）用户参数下一代计时器作为剩下的论点。
强调①:当Nginx工作进程正在尝试关闭时，会发生提前定时器到期，如在Nginx配置中由HUP信号触发的重新加载或Nginx服务器关闭。
当Nginx工作器试图关闭时，不能再调用ngx.timer.at创建具有非零延迟的新定时器，在这种情况下ngx.timer.at将返回nil，还有一个描述错误的字符串，即“进程退出”。
从v0.9.3版本开始，即使Nginx工作进程开始关闭，也允许创建零延迟计时器。
强调②当计时器过期时，计时器回调中的用户Lua代码将在一个“轻线程”中运行，该线程与创建计时器的原始请求完全分离(说明该线程仍然被主线程所join，
并没有detach，即定时器不执行完成，主进程无法退出)。
因此，不能在原始请求和计时器用户回调函数之间共享与创建它们的请求具有相同生存期的对象（如cosockets）。
ngx.timer.at本质上还是开辟一个线程协作运行，但是ngx.timer的运行时间并非执行完ngx.timer.at函数之后立即开始，
而是等待执行ngx.timer.at的协程运行完毕之后再执行 local delay = 5
 local handler
 handler = function (premature)
     -- do some routine job in Lua just like a cron job
     if premature then
         return
     end
     local ok, err = ngx.timer.at(delay, handler)
     if not ok then
         ngx.log(ngx.ERR, "failed to create the timer: ", err)
         return
     end
 end

 local ok, err = ngx.timer.at(delay, handler)
 if not ok then
     ngx.log(ngx.ERR, "failed to create the timer: ", err)
     return
 end
 
 location / {
     ...
     log_by_lua_block {
         local function push_data(premature, uri, args, status)
             -- push the data uri, args, and status to the remote
             -- via ngx.socket.tcp or ngx.socket.udp
             -- (one may want to buffer the data in Lua a bit to
             -- save I/O operations)
         end
         local ok, err = ngx.timer.at(0, push_data,
                                      ngx.var.uri, ngx.var.args, ngx.header.status)
         if not ok then
             ngx.log(ngx.ERR, "failed to create timer: ", err)
             return
         end
     }
 }
 

 

ngx.get_phase
函数原型: str = ngx.get_phase()
函数说明: 检索当前运行的阶段
返回值如下:(https://github.com/openresty/lua-nginx-module#ngxget_phase)
init for the context of init_by_lua*.
init_worker for the context of init_worker_by_lua*.
ssl_cert for the context of ssl_certificate_by_lua*.
ssl_session_fetch for the context of ssl_session_fetch_by_lua*.
ssl_session_store for the context of ssl_session_store_by_lua*.
set for the context of set_by_lua*.
rewrite for the context of rewrite_by_lua*.
balancer for the context of balancer_by_lua*.
access for the context of access_by_lua*.
content for the context of content_by_lua*.
header_filter for the context of header_filter_by_lua*.
body_filter for the context of body_filter_by_lua*.
log for the context of log_by_lua*.
timer for the context of user callback functions for ngx.timer.*.

 

ngx.escape_uri
函数原型: newstr = ngx.escape_uri(str)
函数说明: 做url字符串转化
返回值: 新字符串

 

ngx.thread.spawn
函数原型: co = ngx.thread.spawn(func, arg1, arg2, ...)
函数说明: 创建一个Lua线程(或者协程)执行func函数，func的参数列表是 arg1,arg2

 

ngx.req.set_uri
函数原型: ngx.req.set_uri(uri, jump?)
函数说明: 重写当前请求的url使用形参代替，要求形参必须是lua字符串，当jump为true时，调用ngx.req.set_uri后，
nginx将会根据修改后的uri，重新匹配新的location；如果jump为false，将不会进行locations的重新匹配，而仅仅是修改了当前请求的URI而已。jump的默认值为false。

 

ngx.re.match
函数原型: captures, err = ngx.re.match(subject, regex, options?, ctx?, res_table?)
函数说明: 使用Perl兼容的正则表达式regex与可选选项匹配主题字符串。只返回第一个匹配项[强调]，如果没有找到匹配项，则返回nil。
如果出现错误，例如看到错误的正则表达式或超出PCRE堆栈限制，将返回nil和描述错误的字符串。

支持子表达式 local m, err = ngx.re.match("hello, 1234", "([0-9])[0-9]+")
 -- m[0] == "1234"
 -- m[1] == "1"