Openresty常用指令和参数

1--[[
2参考文档： https://www.nginx.com/resources/wiki/modules/lua/#nginx-api-for-lua
3Nginx Lua模块指令：
4    Nginx共11个处理阶段，而相应的处理阶段是可以做插入式处理，即可插拔式架构；
5    另外指令可以在http、server、server if、location、location if几个范围进行配置：
6
7指令: init_by_lua/init_by_lua_file
8
9    处理阶段:
10        loading-config
11    使用范围:
12        http
13    解释:
14        nginx Master进程加载配置时执行；
15        通常用于初始化全局配置/预加载Lua模块
16
17
18指令: init_worker_by_lua/init_worker_by_lua_file
19
20    处理阶段:
21        starting-worker
22    使用范围:
23        http
24    解释:
25        每个NginxWorker进程启动时调用的计时器，
26        如果Master进程不允许则只会在init_by_lua之后调用；
27        通常用于定时拉取配置/数据，或者后端服务的健康检查
28
29
30指令: set_by_lua/set_by_lua_file
31
32    处理阶段:
33        rewrite
34    使用范围:
35        server,server if,location,location if
36    解释:
37        设置nginx变量，可以实现复杂的赋值逻辑；此处是阻塞的，Lua代码要做到非常快；
38
39
40指令: rewrite_by_lua/rewrite_by_lua_file
41
42    处理阶段:
43        rewrite tail
44    使用范围:
45        http,server,location,location if
46    解释:
47        rewrite阶段处理，可以实现复杂的转发/重定向逻辑；
48
49
50指令: access_by_lua/access_by_lua_file
51
52    处理阶段:
53        access tail
54    使用范围:
55        http,server,location,location if
56    解释:
57        请求访问阶段处理，用于访问控制
58
59
60指令: content_by_lua/content_by_lua_file
61
62    处理阶段:
63        content
64    使用范围:
65        location，location if
66    解释:
67        内容处理器，接收请求处理并输出响应
68
69指令: header_filter_by_lua/header_filter_by_lua_file
70
71    处理阶段:
72        output-header-filter
73    使用范围:
74        http，server，location，location if
75    解释:
76        设置header和cookie
77
78指令:body_filter_by_lua/body_filter_by_lua_file
79
80    处理阶段:
81        output-body-filter
82    使用范围:
83        http，server，location，location if
84    解释:
85        对响应数据进行过滤，比如截断、替换。
86
87
88指令:log_by_lua/log_by_lua_file
89
90    处理阶段:
91        log
92    使用范围:
93        http，server，location，location if
94    解释:
95        log阶段处理，比如记录访问量/统计平均响应时间
96]]
97
98ngx.var
99-- nginx变量，如果要赋值如ngx.var.b = 2，此变量必须提前声明；
100-- 另外对于nginx location中使用正则捕获的捕获组可以使用ngx.var[捕获组数字]获取；
101
102ngx.var.request_uri
103-- 这个变量等于包含一些客户端请求参数的原始URI，它无法修改，请查看$uri更改或重写URI。
104
105
106ngx.var.scheme -- ngx.var.server_addr
107-- HTTP方法（如http，https）。按需使用
108
109ngx.var.server_addruri
110-- 服务器地址，在完成一次系统调用后可以确定这个值，如果要绕开系统调用，则必须在listen中指定地址并且使用bind参数。
111
112ngx.var.uri
113-- 请求中的当前URI(不带请求参数，参数位于$args)，可以不同于浏览器传递的$request_uri的值，它可以通过内部重定向，或者使用index指令进行修改。
114
115ngx.var.server_name
116-- 服务器名称
117
118ngx.var.server_port
119-- 请求到达服务器的端口号。
120
121ngx.var.remote_addr
122-- 获取远程的IP地址
123
124ngx.var.remote_port
125-- 获取远程的端口号
126
127ngx.header
128-- 输出响应头；
129
130ngx.print
131-- 输出响应内容体；
132
133ngx.say
134-- 通ngx.print，但是会最后输出一个换行符；
135
136ngx.exit
137-- 指定状态码退出。
138
139
140ngx.redirect
141-- 重定向；
142
143ngx.status = 301
144-- 设置响应的状态码；
145
146ngx.resp.get_headers()
147-- 获取设置的响应状态码；
148
149ngx.send_headers()
150-- 发送响应状态码, ，当调用ngx.say/ngx.print时自动发送响应状态码；
151
152ngx.headers_sent = true
153-- 判断是否发送了响应状态码。
154
155ngx.req.get_headers
156-- 获取请求头，默认只获取前100，如果想要获取所以可以调用ngx.req.get_headers(0)；
157-- 获取带中划线的请求头时请使用如headers.user_agent这种方式；
158-- 如果一个请求头有多个值，则返回的是table；
159
160ngx.req.get_uri_args
161-- 获取url请求参数，其用法和get_headers类似；
162
163ngx.req.get_post_args
164-- 获取post请求内容体，其用法和get_headers类似，但是必须提前调用ngx.req.read_body()来读取body体
165--（也可以选择在nginx配置文件使用lua_need_request_body on;开启读取body体，但是官方不推荐）；
166
167ngx.req.raw_header
168-- 未解析的请求头字符串；
169
170ngx.req.get_body_data
171-- 为解析的请求body体内容字符串。
172
173ngx.req.set_uri(uri, false)
174-- 可以内部重写uri（可以带参数），等价于 rewrite ^ /lua_rewrite_3；
175-- 通过配合if/else可以实现 rewrite ^ /lua_rewrite_3 break；
176-- 这种功能；此处两者都是location内部url重写，不会重新发起新的
177
178ngx.req.set_uri_args
179-- 重写请求参数，可以是字符串(a=1&b=2)也可以是table；
180
181ngx.escape_uri
182ngx.unescape_uri
183-- uri编码解码；
184
185ngx.encode_args
186ngx.decode_args
187-- 参数编码解码；
188
189ngx.encode_base64
190ngx.decode_base64
191-- BASE64编码解码；
192
193ngx.re.match
194-- nginx正则表达式匹配；
195
196ngx.timer.at
197-- 延时调用相应的回调方法；
198-- ngx.timer.at(秒单位延时，回调函数，回调函数的参数列表)；
199-- 可以将延时设置为0即得到一个立即执行的任务，任务不会在当前请求中执行不会阻塞当前请求，而是在一个轻量级线程中执行。
200
201
202
203-- 指令： init_by_lua
204--[[
205    nginx.conf配置文件中的http部分添加如下代码,
206
207    #共享全局变量，在所有worker间共享
208    lua_shared_dict shared_data 1m;
209    init_by_lua_file /usr/example/lua/init.lua;
210]]
211--init.lua
212--初始化耗时的模块
213local redis = require 'resty.redis'
214local cjson = require 'cjson'
215
216--全局变量，不推荐
217count = 1
218--共享全局内存
219local shared_data = ngx.shared.shared_data
220shared_data:set("count", 1)
221
222-- test.lua
223count = count + 1
224ngx.say("global variable : ", count)
225local shared_data = ngx.shared.shared_data
226ngx.say(", shared memory : ", shared_data:get("count"))
227shared_data:incr("count", 1)
228ngx.say("hello world")
229
230-- 访问如http://192.168.1.2/lua 会发现全局变量一直不变，而共享内存一直递增
231-- global variable : 2 , shared memory : 8 hello world
232-- 另外注意一定在生产环境开启lua_code_cache，否则每个请求都会创建Lua VM实例。
233
234
235
236-- 指令： init_worker_by_lua
237--[[
238    用于启动一些定时任务，比如心跳检查，定时拉取服务器配置等等；
239    此处的任务是跟Worker进程数量有关系的，比如有2个Worker进程那么就会启动两个完全一样的定时任务。
240
241    nginx.conf配置文件中的http部分添加如下代码：
242    init_worker_by_lua_file /usr/example/lua/init_worker.lua;
243
244    另外根据实际情况设置如下指令
245    lua_max_pending_timers 1024;  #最大等待任务数
246    lua_max_running_timers 256;   #最大同时运行任务数
247]]
248
249-- init_worker.lua
250local count = 0
251local delayInSeconds = 3
252local heartbeatCheck = nil
253
254heartbeatCheck = function(args)
255    count = count + 1
256    ngx.log(ngx.ERR, "do check ", count)
257    local ok, err = ngx.timer.at(delayInSeconds, heartbeatCheck)
258    if not ok then
259        ngx.log(ngx.ERR, "failed to startup heartbeart worker...", err)
260    end
261end
262
263heartbeatCheck()
264
265
266
267-- 指令： set_by_lua
268--[[
269    设置nginx变量，我们用的set指令即使配合if指令也很难实现负责的赋值逻辑；
270    语法set_by_lua_file $var lua_file arg1 arg2...;
271    在lua代码中可以实现所有复杂的逻辑，但是要执行速度很快，不要阻塞；
272
273    example.conf配置文件:
274    location /lua_set_1 {
275        default_type "text/html";
276        set_by_lua_file $num /usr/example/lua/test_set_1.lua;
277        echo $num;
278    }
279]]
280-- test_set_1.lua
281local uri_args = ngx.req.get_uri_args()
282local i = uri_args["i"] or 0
283local j = uri_args["j"] or 0
284return i + j
285-- 访问如http://192.168.1.2/lua_set_1?i=1&j=10进行测试。 如果我们用纯set指令是无法实现的。