使用 njs 0.7.7 提高 NGINX 配置的模块化程度和可复用性

发表于2023-05-16 14:29

原文作者：Prabhat Dixit of F5
原文链接：使用 njs 0.7.7 提高 NGINX 配置的模块化程度和可复用性
转载来源：NGINX 官方网站

自 2015 年推出 NGINX JavaScript 模块 (njs)（原名 nginScript）并于 2017 年正式发布以来，我们一直在不断增添新特性，并在数十个版本更新中持续完善我们的代码实现。通常，我们会等到 NGINX Plus 发布后再讨论新版 NGINX JavaScript 的特性，但这次我们对版本 0.7.7 充满期待，已经等不及了！

njs 0.7.7 的重要增强功能可让您的 NGINX 配置变得更加模块化、更加有序、更易于复用：

现在，您可以在适用的上下文中声明 njs 代码，而非全局声明，从而让您的自定义代码更靠近使用点。
njs 代码本身的 hooks 允许您根据执行上下文修改行为。
新的 fs.FileHandle 对象使文件操作更有效率。

如欲了解有关 njs 的更多信息并查看用例列表（提供示例代码），请参阅我们的博文《借助 NGINX JavaScript 模块，充分利用 JavaScript 的强大功能和便利性以快速处理每个请求》。

在本地上下文中声明 JavaScript 代码和变量

在之前的 njs 版本中，您必须导入 JavaScript 代码，并在顶层 http 或 stream 上下文中声明相关变量（使用 js_import、js_path、js_set 和 js_var 指令），这相当于在主文件顶部声明全局变量。但实际调用 JavaScript 函数和变量的指令却出现在子上下文中 — 例如，http location{} 块中的 js_content 指令，stream server{} 块中的 js_access 指令。这会产生两个问题：

对于浏览配置的人员而言，http 和 stream 上下文中的声明基本上是噪声，因为没有指明实际使用相关代码和变量的位置。
而在子上下文中，也无法清晰看到代码和变量是在哪里导入和声明的。尽管我们建议仅在主配置文件 (nginx.conf) 中添加 http{} 和 stream{} 块，并使用 include 指令从 /etc/nginx/conf.d 和 /etc/nginx/stream.d 目录中读取较小的特定函数配置文件，但 NGINX 配置非常灵活 — 您可在多个文件中添加 http{} 和 stream{} 块。在有多人操作你的 NGINX 配置且并非总能遵循既定规则的环境中，这将是一个问题。

在 njs 0.7.7 及更高版本中，您可在使用变量的上下文中导入代码并声明这些变量：

HTTP –

以下指令可以出现在 server 和 location 上下文及 http 上下文中：

js_import
js_path
js_set
js_var

以下指令可以出现在 if 上下文及 location 和 limit_except 上下文中：

js_body_filter
js_content
js_header_filter

Stream — 这些指令可以出现在 server 上下文及 stream 上下文中：

js_import
js_path
js_set
js_var

将特定用例的所有 njs 配置都放到单个文件中还可提高代码的模块化程度和可移植性。

例如，在之前的 njs 版本中，当添加一个新脚本时，您必须同时更改 nginx.conf（添加 js_import 并可能需要添加 js_path、js_set 及 js_var）和调用 JavaScript 函数的文件（此处为 jscode_local.conf）。

http {
    # util.mjs is not actually invoked in this file
    js_import util from util.mjs;

    # This reads in jscode_local.conf, where 'util' is actually invoked
    include /etc/nginx/conf.d/*.conf;
}

server {
    listen 4001;
    location /foo {
        # Where is 'util' defined?# It's not obvious in this context
        js_content util.handler;
    }
}

在 njs 0.7.7 或更高版本中，所有和 util 函数相关的配置都在 jscode_integrated.conf 这个文件中：

server {
    listen 4001;
    js_import util from util.mjs;

    location /foo {
        js_content util.handler;
    }
}

根据执行上下文修改行为

njs 0.7.7 的多个新特性允许您根据执行 JavaScript 代码的上下文（处理阶段）修改其行为。

The HTTP `r.internal` 属性

HTTP r.internal 属性是一个布尔标志，针对内部请求（由添加了 internal 指令的 location{} 块进行处理）设置为 “true”。当一个脚本使用能够在内部和非内部上下文中调用的一般事件处理程序时，您可使用 r.internal 标志来派生 (fork) 逻辑。

以下属于内部请求：

通过 error_page、index、random_index 及 try_files 指令重定向的请求
通过来自上游服务器的 X-Accel-Redirect 响应标头重定向的请求
通过 auth_request 和 mirror 指令、ngx_http_addition_module 块中的指令或服务器端引用 (SSI) 引用虚拟命令（由 ngx_http_ssi_module 模块提供支持）调用的子请求
通过 rewrite 指令更改的请求