OpenResty

OpenResty

官方文档: http://openresty.org/
官方文档完全不明所以, 除了getting-started完全不知道下一步该干啥 (都不知道ngx是什么它就开始用了), 找不到架构图,找不到原理,找不到可用哪些API,核心组件 Lua Nginx Module 藏的要多深有多深

OpenResty 的目标是让 Web 服务直接跑在 Nginx 服务内部,充分利用 Nginx 的非阻塞 I/O 模型,
不仅仅对 HTTP 客户端请求,甚至于对远程后端诸如MySQL,PostgreSQL,Memcaches 以及 Redis 等都进行一致的高性能响应。

执行原理

将 LuaVM嵌入到 Nginx 服务器中,
每个Worker进程使用一个Lua VM（Lua虚拟机），当请求被分配到Worker时，将在这个Lua VM中创建一个协程，协程之间数据隔离，每个协程都具有独立的全局变量。

getting-started

• 安装
  方法一：安装OpenResty (内置了Nginx)
  方法二：Nginx添加lua-nginx-module模块
  (lua-nginx-module模块是 OpenResty 的核心组件。如果您使用此模块，那么您实际上就是在使用 OpenResty)
• 准备配置文件 conf/nginx.conf

worker_processes  1;
error_log logs/error.log;
events {
    worker_connections 1024;
}
http {
    server {
        listen 8080;
        location / {
            default_type text/html;
            content_by_lua_block {
            	# lua code
                ngx.say("<p>hello, world</p>")
            }
        }
    }
}

• 启动

nginx -p `pwd`/ -c conf/nginx.conf

核心模块: lua-nginx-module (ngx_lua)

git仓库: https://github.com/openresty/lua-nginx-module
清晰的文档,比官网清晰: https://openresty-reference.readthedocs.io/en/latest/

ngx_lua是Nginx的一个模块，将Lua嵌入到Nginx中，从而可以使用Lua来编写脚本，
ngx_lua在Lua中进行的IO操作都会委托给Nginx的事件模型，从而实现非阻塞调用。

这样就可以使用Lua编写应用脚本，部署到Nginx中运行
对于开发web应用来说 其开发和Servlet类似，无外乎就是知道接收请求、参数解析、功能处理、返回响应这几步

• 指令
  ngx_lua定义了一系列Nginx配置指令，用于配置何时运行用户Lua脚本以及如何返回Lua脚本的执行结果。

常用指令

https://github.com/openresty/lua-nginx-module?tab=readme-ov-file#directives

指令	说明
lua_shared_dict	创建全局共享的table（多个worker进程共享）
lua_code_cache	*_by_lua_file文件是否cache
lua_package_path	用Lua写的lua外部库路径（.lua文件）
init_by_lua*	master进程启动时挂载的lua代码
init_worker_by_lua*	worker进程启动时挂载的lua代码
set_by_lua*	变量赋值
content_by_lua*	handler模块
log_by_lua

• 指令的不同运行方式
  init_by_lua * :
  • init_by_lua
  • init_by_lua_block
  • init_by_lua_file

init_by_lua '
    print("I need no extra escaping here, for example: \r\nblah")
'
init_by_lua_block { 
	# lua代码块
}

# 加载lua文件
init_by_lua_file  path/name.lua

配置指令的执行顺序

API

https://github.com/openresty/lua-nginx-module?tab=readme-ov-file#nginx-api-for-lua

这里的 Nginx Lua API 只能在配置指令的上下文中 运行的 Lua 代码中 调用。
各种 *_by_lua 、 *_by_lua_block 和 *_by_lua_file 配置指令作为 nginx.conf 文件内 Lua API 的入口。

API 以两个标准包 ngx 和 ndk 的形式暴露给 Lua

 local ngx = require "ngx"
 local ndk = require "ndk"

基础api
ngx.var.*	读写ng变量; Nginx 变量不能即时创建,只能使用已定义的ng变量
ngx.shared.DICT	获取由 lua_shared_dict 指令定义的名为 DICT 的共享内存区域的 shm-based Lua 字典对象
ngx.re.*	正则

线程api
ngx.get_phase	获取当前的指令运行阶段名称
ngx.worker.pid	当前 Nginx 工作进程的进程 pid
ngx.worker.exiting	当前 Nginx 工作进程是否已经正在退出
ngx.thread.spawn	创建一个 “light threads” Lua 协程
ngx.thread.wait	等待一或多个"light threads",返回第一个终止的"light threads"结果
ngx.sleep	睡眠指定秒数，非阻塞（使用定时器实现）

核心常量
ngx.null
ngx.OK	(0)
ngx.ERROR	(-1)
ngx.AGAIN	(-2)
ngx.DONE	(-4)
ngx.DECLINED	(-5)

打印, 日志api
ngx.DEBUG
ngx.INFO
ngx.WARN
ngx.ERR
ngx.log	输出到error.log

编码解码api
ngx.md5
ngx.encode_args
ngx.decode_args
ngx.encode_base64
ngx.decode_base64
ngx.escape_uri
ngx.hmac_sha1
ngx.md5_bin

时间api
ngx.time
ngx.utctime
ngx.now
ngx.now:revert
ngx.update_time
ngx.timer.at
ngx.timer.every
ngx.time.returns()
ngx.time:revert()
ngx.utctime

http请求/响应 api
ngx.ctx.*	请求的lua上下文
ngx.req.*
ngx.resp.*
ngx.status	响应码
ngx.header	响应头
ngx.print	输出响应
ngx.say	ngx.print + 换行符
ngx.flush	刷新响应输出到客户端
ngx.exit	结束请求

HTTP 状态常量
ngx.HTTP_OK	200
ngx.HTTP_CREATED	(201)
ngx.HTTP_ACCEPTED	(202)
ngx.HTTP_NO_CONTENT	(204)
ngx.HTTP_BAD_REQUEST	400
ngx.HTTP_UNAUTHORIZED	(401)
ngx.HTTP_PAYMENT_REQUIRED	(402)
ngx.HTTP_FORBIDDEN	(403)
ngx.HTTP_NOT_FOUND	(404)
ngx.HTTP_CONFLICT	(409)
ngx.HTTP_TOO_MANY_REQUESTS	(429)
ngx.HTTP_INTERNAL_SERVER_ERROR	500
ngx.HTTP_BAD_GATEWAY	(502)
ngx.HTTP_SERVICE_UNAVAILABLE	(502)
ngx.HTTP_GATEWAY_TIMEOUT	(504)