Go gojq 怎样为查询表达式绑定外部变量

Go gojq 绑定外部变量分两处写：编译时通过 gojq.WithVariables([]string{"$minimum", "$group"}) 声明变量名，运行时用 code.Run(input, 75, "review") 按相同顺序提供值。变量名包含美元符号，输入对象input不占变量位置，也不是通过Go map的键名自动绑定。

项目官方地址：https://github.com/itchyny/gojq

先给最小绑定写法

可以把整个契约记成“固定表达式、显式变量表、每次运行传值”。表达式里写 $minimum，变量表里也写 $minimum；Run接收的是值75，不是名称字符串。需要修改阈值时，只改运行参数，不改查询源码。

不要把表达式中出现的顺序误当成绑定顺序。真正决定位置的是传给WithVariables的列表。即使查询先使用group再使用minimum，列表仍然可以先声明minimum，只要运行时保持相同约定。

明确查询参数化解决的问题与受益场景

在JSON过滤、报表筛选和配置处理里，同一个规则常常只改变少量数据参数。把阈值、分类标签直接拼进表达式，会让查询文本和输入值混在一起；字符串中有引号或特殊字符时，还需要额外处理语法转义。

外部变量让调用方把值当数据传递，表达式保持稳定。规则维护者负责查询逻辑，业务调用者负责提供阈值，运维记录也更容易区分“规则变化”和“参数变化”。这是一种接口组织方式；本文没有搜索量或采用率数据，不据此宣称它正在成为行业趋势。

它适合固定查询模板反复运行的场景。如果每次都需要改变字段路径或整段过滤逻辑，那属于查询设计变化，不应把任意代码片段塞进一个字符串变量后期待自动执行。

完成可复用的查询示例

下面的独立入口对记录按分数过滤，并在结果中添加来自外部变量的group。代码适用于已配置 github.com/itchyny/gojq 依赖的Go模块；项目应固定适合自身的模块版本。

package main

import (
    "fmt"
    "github.com/itchyny/gojq"
)

// compileFilter把固定表达式与变量顺序集中在一起维护。
func compileFilter() (*gojq.Code, error) {
    query, err := gojq.Parse(
        `[.[] | select(.score >= $minimum) | {name: .name, group: $group}]`)
    if err != nil {
        return nil, fmt.Errorf("解析查询: %w", err)
    }
    return gojq.Compile(query,
        gojq.WithVariables([]string{"$minimum", "$group"}))
}

// filter通过具名Go参数封装位置绑定，避免调用处把两个变量值放反。
func filter(code *gojq.Code, input any, minimum int, group string) ([]any, error) {
    // 第一个参数是查询输入；后两个值对应声明中的两个变量。
    iter := code.Run(input, minimum, group)
    var results []any
    for {
        value, ok := iter.Next()
        if !ok {
            break
        }
        // 运行期错误也是迭代项，不能只检查编译时的error。
        if err, ok := value.(error); ok {
            return nil, fmt.Errorf("执行查询: %w", err)
        }
        results = append(results, value)
    }
    return results, nil
}

func main() {
    code, err := compileFilter()
    if err != nil {
        fmt.Println("准备查询失败:", err)
        return
    }
    // 对象与数组使用gojq接受的通用容器类型。
    input := []any{
        map[string]any{"name": "cedar", "score": 63},
        map[string]any{"name": "maple", "score": 88},
    }
    results, err := filter(code, input, 75, "review")
    if err != nil {
        fmt.Println(err)
        return
    }
    for _, value := range results {
        data, err := gojq.Marshal(value)
        if err != nil {
            fmt.Println("编码结果失败:", err)
            return
        }
        fmt.Println(string(data))
    }
}

按示例数据和比较条件推导，分数88的maple记录会保留，63分的cedar记录会被排除，保留对象的group内容为review。这里是语义推导，本文没有执行代码或提供实际输出截图。

查询最外层方括号把筛选结果收成一个数组。因此，一次成功执行通常产出一个数组值，即使数组是空的，迭代器也不是“完全没有产出”。Go函数返回的results是查询产出的列表，其中的数组值仍是独立的一项；不要把这两层容器混为一谈。

处理变量顺序数量和类型风险

Run返回迭代器，而不是一个单独的error。多传或少传外部变量值时，错误会作为迭代项出现，所以示例在每次Next之后检查error类型。解析成功、编译成功，也不能替代运行阶段的错误处理。

WithVariables声明的是名字，不是静态类型。示例在Go封装里将minimum限制为int、group限制为string，是为了把调用约定收紧；库不会因为变量名像“阈值”就替业务保证它是数字。

字符串数据应直接作为Go字符串传入，不要额外加一层JSON引号。对象与数组使用兼容的通用容器，比如 map[string]any 和 []any；不能假定任意业务结构体都能直接当作JSON对象访问。

安排接入顺序与观察指标

接入时先固定查询模板和变量列表，再提供一个小型业务函数集中处理传值，最后把迭代错误接到调用方的错误路径。新增变量时同步修改这三个位置，避免一个调用点沿用旧数量。

观察指标可以记录模板标识、编译失败数、运行错误数、查询产出数量和输入规模。日志不要默认保存全部变量内容，尤其变量可能带用户文本或其他敏感数据。本文没有性能实测，复用编译对象也不等于承诺固定加速倍数。

绑定数据减少了拼接语法的需要，但不等于任意查询都受控。允许用户提供完整表达式时，还应另行限制执行资源和输入规模；变量绑定只是数据接口，不是完整的运行隔离方案。

外部变量会自动从环境变量读取吗？

不会。WithVariables与环境加载是不同接口；本例只从Go调用参数传值。

不需要输入JSON时怎么办？

可以把Run的第一个参数设为nil，外部变量值仍放在后面。不要为了凑位置把第一个变量当成查询输入。

变量能保存一段查询并自动执行吗？

字符串变量的内容是数据，不会因为包含查询语法就自动变成代码。需要动态规则时应明确设计查询模板或编译入口。

技术依据：gojq官方接口文档、变量声明选项、运行传值实现。