jq: LuaJIT FFI 绑定到 jq

安装

如果您尚未设置 RPM 仓库订阅，请注册。然后您可以继续以下步骤。

CentOS/RHEL 7 或 Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-jq

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-jq

要在 NGINX 中使用此 Lua 库，请确保已安装 nginx-module-lua。

本文档描述了 lua-resty-jq v0.2.0，于 2025 年 6 月 6 日发布。

lua-resty-jq 是一个小型的 LuaJIT FFI 包装器，用于 jq

使用 lua-resty-jq 的 Hello World

-- <example-input> 来自 https://api.github.com/repos/stedolan/jq/commits?per_page=5
local jq = require "resty.jq".new()

jq:compile("[ .[] | {message: .commit.message, name: .commit.committer.name} ]")
local output = jq:filter(<example-input>)

print(output)

jq:teardown()

运行上述代码将输出（或类似内容）：

[
  {
    "message": "Add some missing code quoting to the manual",
    "name": "William Langford"
  },
  {
    "message": "Reduce allocation on string multiplication",
    "name": "William Langford"
  },
  {
    "message": "Fix multiple string multiplication",
    "name": "William Langford"
  },
  {
    "message": "Fix error handling in strftime",
    "name": "William Langford"
  },
  {
    "message": "Makefile: prepend srcdir to jq.1.prebuilt to fix out of source compilation",
    "name": "William Langford"
  }
]

new

syntax: jq, err = require("resty.jq").new()

分配一个 libjq 上下文。

teardown

syntax: jq:teardown()

销毁 libjq 上下文，释放资源。

compile

syntax: ok, err = jq:compile(program)

如果程序已编译，则返回 true，否则返回 nil 和错误 compilation failed。

请注意，目前无法检查编译错误的详细信息。如果有疑问，请在 CLI jq 中尝试您的程序。

filter

syntax: res, err = jq:filter(data, options)

使用先前编译的程序过滤 data。options 表可以包含修改过滤器行为的标志，类似于 jq 的 CLI 选项的子集：

compact_output: 以紧凑的形式返回输出，不带额外的空格，并且每个 JSON 对象在单独的一行上。默认为 true。设置为 false 以获得“美观”输出。
raw_output: 以原始字符串输出，而不是 JSON 引号。默认值为 false。
join_output: 与 raw_output 相同，但此外不输出换行符分隔符。默认值为 false。
ascii_output: jq 通常将非 ASCII Unicode 代码点作为 UTF-8 输出，即使输入将它们指定为转义序列（如 "\u03bc"）。使用此选项，您可以强制 jq 生成纯 ASCII 输出，每个非 ASCII 字符都替换为等效的转义序列。默认值为 false。
sort_keys: 以排序顺序输出每个对象的字段。默认值为 false。
table_output: 返回一个类似序列的编码结果表，而不是将它们连接成一个字符串。默认值为 false。

此外，filter() 还可以接受一个表作为可选的第三个参数。当提供时，此表将用于存储结果，而不是为每次调用 filter() 创建一个新表：

local buf = {}
local res, err = jq:filter(data, nil, buf)
for _, elem in ipairs(buf) do
  -- ...
end

这样做意味着 options.table_output = true，因此必须显式将此选项设置为 false 以接收字符串结果：

local buf = {}
local res, err = jq:filter(data, { table_output = false }, buf)
print(res)

注意： filter() 在表中添加了一个尾随的 nil，以便长度运算符 (#buf) 和 ipairs(buf) 在执行后返回准确的结果，但它并不会清除表。调用者如果需要，必须自行清除表。

另见

lua-jq

GitHub

您可以在 nginx-module-jq 的 GitHub 仓库中找到此模块的其他配置提示和文档。