注意：本书使用的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自带此模块，不必安装编译）：
# 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.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的指令一样，都存在配置环境的约束问题，因此在使用过程中要确保指令的环境符合预期，例如：
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：
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，输出如下：
# curl -I http://testnginx.com/test Hello,world!
ngx.say将数据作为响应体输出，返回给客户端，并在末尾加上一个回车符。
代码中用到了content_by_lua_block这个指令块，它的主要作用是在HTTP的内容处理阶段生成数据，详见第8.6节。
五、避免I/O阻塞
当Nginx和Lua进行读取磁盘操作时会对Nginx的事件循环造成阻塞，所以在请求中应尽量避免操作磁盘，特别是当文件较大时。
如果Lua使用网络I/O，为了避免出现阻塞的情况，请使用基于Lua API开发的指令，并使用子请求（将在7.13节介绍）来发送网络I/O和磁盘I/O。如果需要频繁读取磁盘，请分离磁盘I/O的任务和网络I/O的任务，避免它们相互影响。
六、定义模块搜索路径
在开发过程中，常常需要编写自定义的模块，或者引入第三方的Lua或C模块，通过下面的配置可以定义相关模块的路径以方便快速查找。
6.1 定义Lua模块的搜索路径
lua_package_path用来设置默认的Lua模块的搜索路径，并配置在http阶段。它支持配置相对路径和绝对路径，其中相对路径是在Nginx启动时由-p PATH 决定的，如果在启动Nginx时没有配置-p PATH，就会使用编译时--prefix的值，此值一般存放在Nginx的$prefix（也可以用${prefix}来表示）变量中。使用lua_package_path设置Lua模块搜索路径的示例如下：
http {
-- lua_package_path在配置中只能出现一次，使用下面的任何一个方法都可以
lua_package_path "/usr/local/nginx_1.12.2/conf/lua_modules/?.lua;;";
lua_package_path "conf/lua_modules/?.lua;;";
lua_package_path "${prefix}conf/lua_modules/?.lua;;";
上述配置中的3种配置方式都指向同一个位置：
第1个是绝对路径；
第2个是相对路径，Nginx编译时用 --prefix=/usr/local/nginx_1.12.2；
第3个也是相对路径，Nginx编译时用 --prefix=/usr/local/nginx_1.12.2 或-p PATH 指定的位置。
第1个配置方式的缺点在于写出了具体文件搜索路径，迁移代码时会比较麻烦。第2个配置方式的缺点在于无法和-p PATH一起使用，如果-p换了位置就会导致这个配置无效。对于第3个配置方式，如果-p的位置换了，${prefix}的值会跟着变换，使用起来比较灵活。所以建议使用第3种配置方式来配置。
lua_package_path可以支持设置多个搜索路径，多个搜索路径之间使用分号分隔就可以了，如下：
lua_package_path "${prefix}conf/lua_modules/?.lua;/opt/lua/?.lua;;";
注意：上述配置中搜索路径的最后出现了;;两个半角分号，代表的是LuaJIT安装时的原始搜索路径，如果在前面的搜索路径里面无法搜索到需要的模块，就会依次搜索后面的路径。
6.2 定义C模块的搜索路径
lua_package_cpath：用来设置C模块的搜索路径，并配置在http阶段。使用方式和lua_package_path一样，如下：
lua_package_cpath "${prefix}conf/c_md/?.so;/opt/c/?.so;;";
七、读写Nginx的内置变量
如果需要读取Nginx的内置变量可以使用ngx.var.VARIABLE。
语法：ngx.var.VAR_NAME
配置环境：set_by_lua，rewrite_by_lua，access_by_lua，content_by_lua，headerfilter by_lua，body_filter_by_lua，og_by_lua*
含义：读写Nginx的变量值。例如HTTP请求头、Nginx set的变量、URL参数，甚至Nginx通过正则表达式捕获的$1、$2等值（获取方式是ngx.var[1]、ngx.var[2]，依此类推）。
示例如下：
server {
listen 80;
server_name testnginx.com;
location ~ ^/([a-z]+)/var.html {
set $a ‘‘;
set $b ‘‘;
set $c ‘‘;
set $d ‘‘;
rewrite_by_lua_block {
local ngx = require "ngx"
--将1赋值给变量a
ngx.var.a = ‘1‘
--获取HTTP请求头中user_agent的值并赋值给变量b
ngx.var.b = ngx.var.http_user_agent
--获取参数test的值赋值给变量c
ngx.var.c = ngx.var.arg_test
--获取location中正则表达式捕获的$1的值并赋值给变量d
ngx.var.d = ngx.var[1]
}
echo $a;
echo $b;
echo $c;
echo $d;
}
执行结果如下：
# curl -i ‘http://testnginx.com/nginx/var.html?test=12132&a=2&b=c&dd‘ HTTP/1.1 200 OK Server: nginx/1.12.2 Date: Thu, 07 Jun 2018 07:22:32 GMT Content-Type: text/html Transfer-Encoding: chunked Connection: keep-alive 1 curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.19.1 Basic ECC zlib/1.2.3 libidn/1.18 libssh2/1.4.2 12132 nginx
如果是未定义的Nginx变量，是无法直接在Lua中进行读取的。而且有些变量只能读取，无法进行修改，如$query_string、$arg_PARAMETER和$http_NAME。
八、控制请求头
在4.1节中讲了Nginx中控制请求头的指令，在Lua API中也有类似的指令。
8.1 添加请求头
指令：ngx.req.set_header
语法：ngx.req.set_header(header_name, header_value)
配置环境：set_by_lua，rewrite_by_lua，access_by_lua，content_by_lua，headerfilter by_lua，body_filter_by_lua
含义：添加或修改当前HTTP的请求头，如果请求头已经存在，则会被替换成新的值。通过此方式设置的请求头会被继承到子请求中。
示例：设置一个名为Test_Ngx_Ver，值为1.12.2的请求头：
ngx.req.set_header("Test_Ngx_Ver", "1.12.2")
ngx.req.set_header支持给同一个请求头设置多个值，用数组的方式添加：
ngx.req.set_header("Test", {"1", "2"})
多个值的输出结果：
Test: 1 Test: 2
8.2 清除请求头
指令：ngx.req.clear_header
语法：ngx.req.clear_header(header_name)
配置环境：set_by_lua，rewrite_by_lua，access_by_lua，content_by_lua，headerfilter by_lua，body_filter_by_lua
含义：清除当前请求中指定的请求头。清除后，如果存在未执行的子请求，则子请求会继承清除后的请求头。
示例：
ngx.req.clear_header("Test_Ngx_Ver")
还有一种清除请求头的方式：
ngx.req.set_header("Test_Ngx_Ver", nil)
8.3 获取请求头
指令：ngx.req.get_headers
语法：headers = ngx.req.get_headers(max_headers?, raw?)
配置环境：set_by_lua，rewrite_by_lua，access_by_lua，content_by_lua，headerfilter by_lua，body_filter_by_lua，log_by_lua*
含义：获取当前请求的全部请求头，并返回一个Lua的table类型的数据：
示例：
server {
listen 80;
server_name testnginx.com;
location / {
content_by_lua_block {
local ngx = require "ngx";
local h = ngx.req.get_headers()
for k, v in pairs(h) do
ngx.say(‘Header name: ‘,k, ‘ value:‘,v)
end
--因为是table，所以可以使用下面的方式读取单个响应头的值
ngx.say(h["host"])
}
}
}
输出结果如下：
# curl -i ‘http://testnginx.com/test?=12132&a=2&b=c&dd‘ HTTP/1.1 200 OK Server: nginx/1.12.2 Date: Fri, 08 Jun 2018 07:46:38 GMT Content-Type: application/octet-stream Transfer-Encoding: chunked Connection: keep-alive Header name:host value: testnginx.com Header name:accept value: */* Header name:user-agent value: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.19.1 Basic ECC zlib/1.2.3 libidn/1.18 libssh2/1.4.2 testnginx.com