平台开发——Nginx学习——nginx变量（待排版完善）

- 日理万妓 2023-02-23 12:14 9阅读 0赞

在 Nginx 配置中，变量只能存放一种类型的值，因为也只存在一种类型的值，那就是字符串

set $a "hello world";

Nginx 变量名前面有一个 $ 符号，这是记法上的要求。所有的 Nginx 变量在 Nginx 配置文件中引用时都须带上 $ 前缀。

我们来看一个比较完整的配置示例：

server { 
        listen 8080;
    
        location /test { 
            set $foo hello;
            echo "foo: $foo";
        }
    }

这个例子省略了 nginx.conf 配置文件中最外围的 http 配置块以及 events 配置块。使用 [curl][] 这个 HTTP 客户端在命令行上请求这个 /test 接口，我们可以得到

$ curl 'http://localhost:8080/test'
    命令行显示：foo: hello

Nginx 变量的创建和赋值操作发生在全然不同的时间阶段。Nginx 变量的创建只能发生在 Nginx 配置加载的时候，或者说 Nginx 启动的时候；而赋值操作则只会发生在请求实际处理的时候。这意味着不创建而直接使用变量会导致启动失败，同时也意味着我们无法在请求处理时动态地创建新的 Nginx 变量。

Nginx 变量一旦创建，其变量名的可见范围就是整个 Nginx 配置，甚至可以跨越不同虚拟主机的 server 配置块。 举例如下：

server { 
            listen 8080;
    
            location /foo { 
                echo "foo = [$foo]";
            }
    
            location /bar { 
                set $foo 32;
                echo "foo = [$foo]";
            }
        }

$ curl 'http://localhost:8080/foo'
        foo = []
    
    $ curl 'http://localhost:8080/bar'
        foo = [32]
    
    $ curl 'http://localhost:8080/foo'
        foo = []

从这个例子我们可以看到，set 指令因为是在 location /bar 中使用的，所以赋值操作只会在访问 /bar 的请求中执行。而请求 /foo 接口时，我们总是得到空的 $foo 值，因为用户变量未赋值就输出的话，得到的便是空字符串。

从这个例子我们可以窥见的另一个重要特性是，Nginx 变量名的可见范围虽然是整个配置，但每个请求都有所有变量的独立副本，或者说都有各变量用来存放值的容器的独立副本，彼此互不干扰。比如前面我们请求了 /bar 接口后，$foo 变量被赋予了值 32，但它丝毫不会影响后续对 /foo 接口的请求所对应的 $foo 值（它仍然是空的！），因为各个请求都有自己独立的 $foo 变量的副本。

————————————————————————————————————————————————————————————————————————————————————————————————

关于 Nginx 变量的另一个常见误区是认为变量容器的生命期，是与 location 配置块绑定的。其实不然。我们来看一个涉及“内部跳转”的例子：

server { 
        listen 8080;
    
        location /foo { 
            set $a hello;
            echo_exec /bar;    #内部跳转命令 echo_exec，也可以用 rewrite ^ /bar;
        }
    
        location /bar { 
            echo "a = [$a]";
        }
    }

这里我们在 location /foo 中，使用第三方模块 ngx\_echo 提供的 echo\_exec 配置指令，发起到 location /bar 的“内部跳转”。所谓“内部跳转”，就是在处理请求的过程中，于服务器内部，从一个 location 跳转到另一个 location 的过程。这不同于利用 HTTP 状态码 301 和 302 所进行的“外部跳转”，因为后者是由 HTTP 客户端配合进行跳转的，而且在客户端，用户可以通过浏览器地址栏这样的界面，看到请求的 URL 地址发生了变化。内部跳转和 Bourne Shell（或 Bash）中的 exec 命令很像，都是“有去无回”。另一个相近的例子是 C 语言中的 goto 语句。

既然是内部跳转，当前正在处理的请求就还是原来那个，只是当前的 location 发生了变化，所以还是原来的那一套 Nginx 变量的容器副本。对应到上例，如果我们请求的是 /foo 这个接口，那么整个工作流程是这样的：先在 location /foo 中通过 set 指令将 $a 变量的值赋为字符串 hello，然后通过 echo\_exec 指令发起内部跳转，又进入到 location /bar 中，再输出 $a 变量的值。因为 $a 还是原来的 $a，所以我们可以期望得到 hello 这行输出。测试证实了这一点：

$ curl localhost:8080/foo
    a = [hello]

但如果我们从客户端直接访问 /bar 接口，就会得到空的 $a 变量的值，因为它依赖于 location /foo 来对 $a 进行初始化。

除了用户自己定义的“用户变量”，还有Nginx 核心和各个 Nginx 模块提供的“内建变量”（许多内建变量都是只读的）  
比如： u r i 、 uri、 uri、request\_uri、$arg\_XXX、 $args args可以用户修改  
例子：

server { 
            listen 8080;
    
            location /test { 
            echo "uri = $uri";
            echo "request_uri = $request_uri";
            echo "args = $args"; #当前请求的 URL 参数串（即请求 URL 中问号后面的部分，如果有的话）
            echo "a = $arg_a";
            set $args "a=1&b=2"; #修改参数串
            echo "a = $arg_a"; 
            }
    }

$ curl 'localhost:8080/test?a=10&b=7'
    uri = /test
    request_uri = /test?a=10&b=7
    args = a=10&b=7
    a = 10
    a = 1

当我们读取 $args 时，Nginx 会执行一小段代码，从 Nginx 核心中专门存放当前 URL 参数串的位置去读取数据；而当我们改写 $args 时，Nginx 会执行另一小段代码，对相同位置进行改写。Nginx 的其他部分在需要当前 URL 参数串的时候，都会从那个位置去读数据，所以我们对 $args 的修改会影响到所有部分的功能。

与面向对象编程中的“存取器”概念相对应，Nginx 变量也是支持绑定“存取处理程序”的。Nginx 模块在创建变量时，可以选择是否为变量分配存放值的容器，以及是否自己提供与读写操作相对应的“存取处理程序”。

不是所有的 Nginx 变量都拥有存放值的容器。拥有值容器的变量在 Nginx 核心中被称为“被索引的”（indexed）；反之，则被称为“未索引的”（non-indexed）。  
在设置了“取处理程序”的情况下，Nginx 变量也可以选择将其值容器用作缓存，这样在多次读取变量的时候，就只需要调用“取处理程序”计算一次。

Nginx 的这个 map 指令就可以用于定义两个 Nginx 变量之间的映射关系，或者说是函数关系。回到上面这个例子，我们用 map 指令定义了用户变量 $foo 与 $args 内建变量之间的映射关系。特别地，用数学上的函数记法 y = f(x) 来说，我们的 $args 就是“自变量” x，而 $foo 则是“因变量” y，即 $foo 的值是由 $args 的值来决定的，或者按照书写顺序可以说，我们将 $args 变量的值映射到了 $foo 变量上。

现在我们再来看 map 指令定义的映射规则：

map $args $foo { 
        default     0;
        debug       1;
    }

花括号中第一行的 default 是一个特殊的匹配条件，即当其他条件都不匹配的时候，这个条件才匹配。当这个默认条件匹配时，就把“因变量” $foo 映射到值 0. 而花括号中第二行的意思是说，如果“自变量” $args 精确匹配了 debug 这个字符串，则把“因变量” $foo 映射到值 1. 将这两行合起来，我们就得到如下完整的映射规则：当  a r g s 的 值 等 于 d e b u g 的 时 候 ， args 的值等于 debug 的时候， args的值等于debug的时候，foo 变量的值就是 1，否则 $foo 的值就为 0.

不是因为我们不想把 map 语句直接挪到 location 配置块中，而是因为 map 指令只能在 http 块中使用！

————————————————————————————————————————————————————————————————————————  
在 Nginx 世界里有两种类型的“请求”，一种叫做“主请求”（main request），而另一种则叫做“子请求”（subrequest）。

所谓“主请求”，就是由 HTTP 客户端从 Nginx 外部发起的请求。我们前面见到的所有例子都只涉及到“主请求”，包括 （二） 中那两个使用 echo\_exec 和 rewrite 指令发起“内部跳转”的例子。

而“子请求”则是由 Nginx 正在处理的请求在 Nginx 内部发起的一种级联请求。“子请求”在外观上很像 HTTP 请求，但实现上却和 HTTP 协议乃至网络通信一点儿关系都没有。它是 Nginx 内部的一种抽象调用，目的是为了方便用户把“主请求”的任务分解为多个较小粒度的“内部请求”，并发或串行地访问多个 location 接口，然后由这些 location 接口通力协作，共同完成整个“主请求”。当然，“子请求”的概念是相对的，任何一个“子请求”也可以再发起更多的“子子请求”，甚至可以玩递归调用（即自己调用自己）。当一个请求发起一个“子请求”的时候，按照 Nginx 的术语，习惯把前者称为后者的“父请求”（parent request）。

下面就来看一个使用了“子请求”的例子：

location /main { 
        echo_location /foo;
        echo_location /bar;
    }
    
    location /foo { 
        echo foo;
    }
    
    location /bar { 
        echo bar;
    }

这里在 location /main 中，通过第三方 ngx\_echo 模块的 echo\_location 指令分别发起到 /foo 和 /bar 这两个接口的 GET 类型的“子请求”。由 echo\_location 发起的“子请求”，其执行是按照配置书写的顺序串行处理的，即只有当 /foo 请求处理完毕之后，才会接着处理 /bar 请求。这两个“子请求”的输出会按执行顺序拼接起来，作为 /main 接口的最终输出：

$ curl 'http://localhost:8080/main'
    foo
    bar

我们看到，“子请求”方式的通信是在同一个虚拟主机内部进行的，所以 Nginx 核心在实现“子请求”的时候，就只调用了若干个 C 函数，完全不涉及任何网络或者 UNIX 套接字（socket）通信。我们由此可以看出“子请求”的执行效率是极高的。

————————————————————————————————————————————————————————————————  
请看下面这个例子：

location /test { 
        content_by_lua ' if ngx.var.arg_name == nil then ngx.say("name: missing") else ngx.say("name: [", ngx.var.arg_name, "]") end ';
    }

这个例子和前一个例子功能上非常接近，除了我们在 /test 接口中使用了 ngx\_lua 模块的 content\_by\_lua 配置指令，嵌入了一小段我们自己的 Lua 代码来对 Nginx 变量 $arg\_name 的特殊值进行判断。在这个例子中，当 $arg\_name 的值为“没找到”（或者“不合法”）时，/foo 接口会输出 name: missing 这一行结果:

$ curl 'http://localhost:8080/test'
    name: missing

因为这是我们第一次接触到 ngx\_lua 模块，所以需要先简单介绍一下。 ngx\_lua 模块将 Lua 语言解释器（或者 LuaJIT 即时编译器）嵌入到了 Nginx 核心中，从而可以让用户在 Nginx 核心中直接运行 Lua 语言编写的程序。我们可以选择在 Nginx 不同的请求处理阶段插入我们的 Lua 代码。这些 Lua 代码既可以直接内联在 Nginx 配置文件中，也可以单独放置在外部 .lua 源码文件（或者 Lua 字节码文件）里，然后在 Nginx 配置文件中引用这些文件的路径。

回到上面这个例子，我们在 Lua 代码里引用 Nginx 变量都是通过 ngx.var 这个由 ngx\_lua 模块提供的 Lua 接口。比如引用 Nginx 变量 $VARIABLE 时，就在 Lua 代码里写作 ngx.var.VARIABLE 就可以了。当 Nginx 变量 $arg\_name 为特殊值“没找到”（或者“不合法”）时， ngx.var.arg\_name 在 Lua 世界中的值就是 nil，即 Lua 语言里的“空”（不同于 Lua 空字符串）。我们在 Lua 里输出响应体内容的时候，则使用了 ngx.say 这个 Lua 函数，也是 ngx\_lua 模块提供的，功能上等价于 ngx\_echo 模块的 echo 配置指令。

参考资料：[http://openresty.org/download/agentzh-nginx-tutorials-zhcn.html][http_openresty.org_download_agentzh-nginx-tutorials-zhcn.html]

[curl]: http://www.ruanyifeng.com/blog/2019/09/curl-reference.html
[http_openresty.org_download_agentzh-nginx-tutorials-zhcn.html]: http://openresty.org/download/agentzh-nginx-tutorials-zhcn.html