距离上一次更新该文章已经过了 732 天，文章所描述的內容可能已经发生变化，请留意。
摘自：http://www.daileinote.com/computer/openresty/06
下面介绍的 Lua API 可以在 *_by_lua_block 和 *_by_lua_file 指定的 Lua 代码里调用，这些 API 很好的桥接了 nginx 和 Lua。
ngx.arg
plaintext
1 | syntax: val = ngx.arg[index] |
在响应体过滤时候 ngx.arg[1] 代表响应体内容，ngx.arg[2] 代表该块的标志位。参照 配置指令 body_filter_by_lua_block。
ngx.var.VARIABLE
这个指令可以获取 nginx 的变量，注意，在一次请求里 nginx 变量读取的时候会分配一次内存，在请求结束的时候会释放，所以如果需要反复使用该变量的值，可以保存为本地 lua 变量。
未定义的变量返回 nil，定义了未初始化的返回空字符串。
把变量设置为 nil，会清除该变量。
bash
1 | ngx.var.args = nil |
例子
bash
1 | location /f { |
输出到 error.log 文件，日志级别为 ngx.NOTICE。等同于
lua
1 | ngx.log(ngx.NOTICE,...) |
nil、true、false、ngx.null(null) 都会以字符串形式输出到日志。默认最大长度为 2048，除非修改 src/core/ngx_log.h 的 NGX_MAX_ERROR_STR 宏。
ngx.log
同上，记录日志，可以指定日志级别。
bash
1 | error_log logs/error.log notice; |
ngx.ctx
该表格可以存储每个请求的上下文数据，在同一个请求里共享，生命周期伴随当前请求。
不到非使用不可，建议不要用，因为查询 ngx.ctx 需要调用元方法，比较耗时。
bash
1 | location /test { |
但是子请求会有其自己的上下文。
bash
1 | location /sub { |
内部重定向将会清空 ngx.ctx 数据。
bash
1 | location /new { |
如果想要在自己的模块函数里操作 ngx.ctx，可以当做参数传递，因为表格传递的是引用，请求结束后会自动销毁。
lua
1 | -- mymodule.lua |
ngx.print
输出响应体，如果响应头没发送，那么会先发送响应头。成功返回1 失败返回 nil 加错误信息。可以输出 nil、true、false 为响应的字符串，ngx.null 会输出成 null。如果传入的是表格，会一个接一个的输出。
ngx.print() 是异步调用，会立马返回，不会等到数据全部存入发送缓冲区。想同步操作，可以在后面跟上 ngx.flush(true)。
但是有一点需要注意，ngx.print 会调用所有的响应体过滤链，同步模式可能会比较耗时。
ngx.say
同上，只是会在最后附上换行符。
bash
1 | location /f { |
由于 ngx.print() 或者 ngx.say() 会一个接一个的输出，所以上面的 body_filter_by_lua* 响应体过滤至少会调用 4 次。
ngx.flush
plaintext
1 | ngx.flush(bool) |
刷新响应体内容到系统的发送缓冲区，接收一个bool参数，默认为 false，代表异步，立马返回。如果设为 true，那么为同步模式，要等到所有的内容经过过滤链后才返回，或者是超时时间到了也返回。
ngx.status
设置响应状态码，必须在响应头发送之前。
ngx.exit
plaintext
1 | ngx.exit(status) |
当 status >= 200，将会终止当前请求并返回状态码。当 status == 0，只会终止当前阶段，会继续执行下一阶段。status 一般由常量指定，也可以直接用数字代替。
最好配合 return 使用来强调该请求已经结束。
bash
1 | location /f { |
ngx.eof
plaintext
1 | syntax: ok, err = ngx.eof() |
主动标记响应体的结束，相当于 nginx 里面发送一个有 last_buf 标记的链。如果不是 keepalive，那么会主动让http客户端关闭连接。利用这个特性，我们可以在发送完响应体后让客户端关闭连接，然后我们可以在后台继续处理额外的事情而不必让客户端干等着。
bash
1 | location /f { |
但是如果是创建子请求到上游服务器，必须要配置 upstream 模块忽略客户端连接的关闭，因为在默认的情况下，如果客户端连接关闭，那么 ngx_http_proxy_module 模块会关闭子请求和主请求。所以必须要有如下配置
bash
1 | proxy_ignore_client_abort on; |
当然后台工作更好的方式是利用 ngx.timer.at 定时器。
ngx.sleep
plaintext
1 | syntax: ngx.sleep(seconds) |
非阻塞睡眠，精度到毫秒
lua
1 | --睡眠1毫秒 |
核心常量
bash
1 | ngx.OK (0) |
ngx.exit 接受 ngx.OK、ngx.ERROR、ngx.DECLINED。
ngx.null 常量在 Lua 表格中代表 nil。
HTTP 请求方法常量
bash
1 | ngx.HTTP_GET |
状态码常量
bash
1 | value = ngx.HTTP_CONTINUE (100) (first added in the v0.9.20 release) |
日志级别常量
bash
1 | ngx.STDERR |
本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 小五的个人杂货铺！
微信- 支付宝
相关推荐
2023-07-14
openresty(lua-API-子请求,(内部)重定向)
摘自：http://www.daileinote.com/computer/openresty/07 内部子请求子请求在内部执行，非常高效。子请求会缓冲所有的响应体，如果响应体很大，建议用 cosockets 来操作。 子请求默认情况下会继承所有父请求的请求头。 ngx.location.capture1syntax: res = ngx.location.capture(uri, options?) 基本用法 1res = ngx.location.capture(uri) res是一个表格，包含4个成员 res.status 子请求响应的状态码res.header 表格的形式存放子请求的响应头，如果有同名多个响应头，那么值也为表格，比如假设响应头有3个 Set-Cookie。 123Set-Cookie: a=3Set-Cookie: foo=barSet-Cookie: baz=blah 那么 res.header["Set-Cookie"] 里的值为 1{"a=3", "foo=bar",...
2023-07-14
openresty(lua-API-常用组件)
摘自：http://www.daileinote.com/computer/openresty/09 下面列出 lua-nginx-module 模块内置的一些组件。 ngx.escape_uri1syntax: newstr = ngx.escape_uri(str) 转义uri。 ngx.unescape_uri1syntax: newstr = ngx.unescape_uri(str) 取消转义。 12345678910location = /test { content_by_lua_block { ngx.say(ngx.escape_uri("http://www.freecls.com?name=freecls&age=28")) ngx.say(ngx.unescape_uri("http%3A%2F%2Fwww.freecls.com%3Fname%3Dfreecls%26age%3D28")) }...
2023-07-14
openresty(lua-API-请求相关)
摘自：http://www.daileinote.com/computer/openresty/08 ngx.req.is_internal1syntax: is_internal = ngx.req.is_internal() 判断是否为内部请求。 ngx.get_phase1syntax: str = ngx.get_phase() 获取当前阶段名 1234567891011121314init #init_by_lua*.init_worker #init_worker_by_lua*.ssl_cert #ssl_certificate_by_lua*.ssl_session_fetch #ssl_session_fetch_by_lua*.ssl_session_store #ssl_session_store_by_lua*.set #set_by_lua*.rewrite #rewrite_by_lua*.balancer ...
