kk Blog —— 通用基础

http://www.04007.cn/article/430.html

在使用lua时，也许我们很多时候都只用了它几个基础的方法：比如http://www.04007.cn/article/129.html 这里面的content_by_lua，或者content_by_lua_file方法。在nginx+lua的脚本中，我们常用的ngx.say,以及ngx.log等，但实际ngx.还有很多好用的方法。

lua_nginx_module中可使用的指令列表：

在lua程序脚本中可使用的操作方法及可取得的变量和常量列表

https://blog.51cto.com/xikder/2331336

https://blog.51cto.com/xikder/2331368

https://blog.51cto.com/xikder/2331504

本章将会讲解基于LuaJIT的Lua-Nginx-Module，它作为Nginx的第三方开源软件，拥有十分丰富的功能，可以轻松完成高并发的业务需求。

注意：本书使用的Lua-Nginx-Module版本是0.10.13。Nginx API for Lua将被简称为Lua API，而Lua-Nginx-Module则被简称为Ngx_lua。后面章节中涉及到的Lua API大部分是包含参数的，如果参数以?结尾，代表这个参数是可选的，如在指令ngx.req.get_headers (max_headers?, raw?)中，max_headers和raw是可选的。

一、Nginx和OpenResty

首先，来认识一下OpenResty，它是一个基于Nginx和Lua开发的高性能的Web平台，包含大量成熟的第三方库，可快速搭建出高性能的Web服务器，支持常用的反向代理、网关系统、Web应用等。

如果在Nginx上使用Ngx_lua，需要先进行编译；而OpenResty已经包含此模块，不需要再进行编译了。读者可以自由选择使用Nginx或OpenResty来搭建服务，如果无法抉择，可参考如下场景。

使用Nginx编译Ngx_Lua的场景

HTTP代理服务器：复杂度较小，只需部分组件即可，且代理服务器一般由运维人员进行维护。使用Nginx的稳定版进行编译，在性能方面会更有保障，而OpenResty是Nginx的主线版，可能会不定期更新。

OpenResty的使用场景

API服务：业务需求多，需要大量组件。
网关系统：需要大量组件和指令来实现动态组件功能。
Web应用服务器：业务服务、页面服务等，如详情页业务的开发。
使用Nginx编写的Lua代码都可以直接迁移到OpenResty上；反之却不一定可行，毕竟OpenResty的组件更多。

二、安装Ngx_lua

请先安装LuaJIT 2.1.0-beta3（详见第6.2节）并需要编译ngx_devel_kit模块。 下面是在Nginx上的安装方式（OpenResty自带此模块，不必安装编译）：

1
2
3
4
5
6
7
8
9
10
11

# wget 'http://nginx.org/download/nginx-1.12.2.tar.gz'
# git clone https://github.com/simplresty/ngx_devel_kit.git
# git clone https://github.com/openresty/lua-nginx-module.git
# tar -xzvf nginx-1.12.2.tar.gz
# cd nginx-1.12.2/
# ./configure --prefix=/usr/local/nginx_1.12.2 \
     --add-module=../ngx_devel_kit \
     --add-module=../lua-nginx-module
     --with-ld-opt="-Wl,-rpath,$LUAJIT_LIB"

# make && make install

并不是每个Nginx版本都支持最新的Ngx_lua，目前已知支持最新Ngx_lua的Nginx版本如下：

1
2
3
4
5
6
7
8

1.13.x (last tested: 1.13.6)
1.12.x
1.11.x (last tested: 1.11.2)
1.10.x
1.9.x (last tested: 1.9.15)
1.8.x
1.7.x (last tested: 1.7.10)
1.6.x

如需获取最新版本的支持动态，请参考https://github.com/openresty/lua-nginx-module# nginx-compatibility。

三、牢记context标识

Ngx_lua API指令和Nginx的指令一样，都存在配置环境的约束问题，因此在使用过程中要确保指令的环境符合预期，例如：

1
2
3
4

ngx.var.VARIABLE
语法：ngx.var.VAR_NAME
context(配置环境)：set_by_lua*，rewrite_by_lua*，access_by_lua*，content_by_lua*，header_ filter_by_lua*，body_filter_by_lua*，log_by_lua*
context即配置环境，第一次接触Ngx_lua的读者看到这样的配置环境可能会觉得难以理解，因为这还涉及到Ngx_Lua的执行阶段（后面会有介绍）。

四、Hello world

首先，还是来一条经典语句“Hello, world”，在Nginx配置中加入一个server：

1
2
3
4
5
6
7
8
9
10
11
12
13

server {
    listen       80;
    server_name  testnginx.com;
    charset koi8-r;
    location = /test {
     #设置文件使用的默认MIME-type,将会增加一个Content-Type:text/plain的响应头
     default_type 'text/plain';    
     -- content_by_lua_block执行阶段
     content_by_lua_block {    
         ngx.say('Hello,world!')
     }
    }
}

访问这个server，输出如下：

1
2

#  curl -I http://testnginx.com/test
Hello,world!    

ngx.say将数据作为响应体输出，返回给客户端，并在末尾加上一个回车符。

代码中用到了content_by_lua_block这个指令块，它的主要作用是在HTTP的内容处理阶段生成数据，详见第8.6节。

https://blog.csdn.net/trustnature/article/details/94417336

由于nginx默认不读取请求体的数据，因此当 Lua 通过 ngx.var.request_body 的方式获取请求体时会发现数据为空，那么，该如何获得请求体的数据呢？

方式一：lua_need_request_body

1
2
3
4
5

语法：lua_need_request_body<on|off>

默认值：off

环境：http、server、location、

含义：默认为off，即不读取请求体。如果设置为on，则表示强制读取请求体，此时，可以通过 ngx.var.request_body 来获取请求体的数据。但需要注意一种情况，$request_body 存在与内存中，如果它的字节大小超过Nginx配置的 client_body_buffer_size 的值，Nginx就会把请求体存放到临时文件中。此时数据就不存在与内存中了，这会导致 $request_body 为空，所以需要设置 client_body_buffer_size 和 client_max_body_size 的值相同，避免出现这种情况。

这种配置方式不够灵活，Ngx_Lua官网也不推荐使用此方法。

方式二：ngx.req.read_body

1
2
3

语法：ngx.req.read_body()

环境：rewrite_by_lua*、access_by_lua*、content_by_lua*

含义：同步读取客户端请求体，且不会阻塞Nginx的事件循环。使用此指令后，就可以通过 ngx.req.get_body_data 来获取请求体的数据了。按如果使用临时文件来存放请求体，就需要先使用函数 ngx.req.get_body_file 来获取临时文件名，再读取临时文件中的请求体数据。

1
2
3
4
5

指令：ngx.req.get_body_data

语法：data = ngx.req.get_body_data()

环境：rewrite_by_lua*、access_by_lua*、content_by_lua*、log_by_lua*

含义：执行 ngx.req.read_body 指令后，可以使用本指令在内存中获取请求体数据，结果会返回一个Lua的字符串类型数据。如果要获取Lua的table类型的数据，则需要使用 ngx.req.get_post_args

1
2
3
4
5

指令：ngx.req.get_post_data

语法：args,err=ngx.req.get_post_args(max_args?)

环境：rewrite_by_lua*、access_by_lua*、content_by_lua*、header_filter_by_lua*、body_filter_by_lua*、log_by_lua*

含义：在执行 ngx.req.read_body 指令后，可以使用本指令读取包含当前请求在内的所有POST值请求的查询参数，返回一个Lua的table类型的数据。max_args 参数的作用时限制参数的数量。为了服务的安全，最多支持使用100个参数（包括重复的参数），超过限制的参数会被忽略。如果max_args为0，则表示关闭此限制；但为了避免被无穷多的参数攻击，不要将max_args设置为0，如果最多支持使用10个参数，则应配置为 ngx.req.get_post_args(10)。

使用场景：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

content_by_lua_block {
	local ngx = require "ngx"
	ngx.req.read_body()
	local data = ngx.req.get_body_data()
	if data then
		ngx.print('ngx.req.get_body_data:',data,')
		return
	else
		lcoal file = ngx.req.get_body_file()
		if file then
			ngx.say("body is in file",file)
		else
			ngx.say("no body found")
		end
	end
}