Go gojq 的 input 为什么需要单独提供输入迭代器

在 Go 中把 gojq 嵌入程序时，input 和 inputs 读取的并不是 code.Run(v) 的那个主输入。它们代表另一条额外输入流，而这条流默认没有开启，所以需要在编译查询时显式传入 gojq.WithInputIter。

官方地址：https://pkg.go.dev/github.com/itchyny/gojq

可以把 Run(v) 理解为“当前查询正在处理的对象”，把 WithInputIter(iter) 理解为“查询中 input/inputs 可以继续消费的对象序列”。如果只给 Run 传值，不能自动打开 input/inputs。

先分清两条输入通道

gojq 的库 API 同时面对两类输入：查询的主对象由 Query.Run 或 Code.Run 接收；查询表达式中的 input、inputs 则从编译选项配置的 Iter 中读取。官方文档明确说明，后者默认被禁用，并且要区分“查询输入”和“input(s) 函数的值”。

这正是很多代码第一次接入时的误区：把 JSON 传给 Run，然后在查询里写 inputs，以为它会继续遍历这个 JSON。实际上，两者是不同的来源。尤其是使用类似命令行 --null-input 的场景，主输入可以传 nil，额外数据仍由输入迭代器提供。

用 gojq.NewIter 提供固定输入

最小写法是先解析查询，再用 gojq.Compile 加上 WithInputIter。下面的查询用 inputs 逐项取出三个对象，主输入则明确传入 nil：

package main

import (
    "fmt"
    "log"

    "github.com/itchyny/gojq"
)

func main() {
    // inputs 从额外输入流中逐项读取对象，主查询输入不承担这项工作。
    query, err := gojq.Parse(`inputs | .name`)
    if err != nil {
        log.Fatal(err)
    }

    // NewIter 把固定值包装成 gojq.Iter，顺序就是 inputs 的读取顺序。
    code, err := gojq.Compile(
        query,
        gojq.WithInputIter(gojq.NewIter(
            map[string]any{"name": "Ada"},
            map[string]any{"name": "Grace"},
            map[string]any{"name": "Linus"},
        )),
    )
    if err != nil {
        log.Fatal(err)
    }

    // nil 表示本例不提供独立的主查询对象；inputs 仍有自己的输入流。
    iter := code.Run(nil)
    for {
        value, ok := iter.Next()
        if !ok {
            break // false 表示结果迭代器已经结束。
        }
        if err, ok := value.(error); ok {
            log.Fatal(err) // 错误也可能作为迭代项返回。
        }
        fmt.Println(value)
    }
}

这个例子中，gojq.NewIter 只负责把已有值变成 Iter，并没有改变查询语义。真正打开 input/inputs 能力的是 WithInputIter。如果把它删掉，查询就没有可供 inputs 消费的输入流。

为什么不能只把数据传给 Run

Run(v) 的参数会成为滤镜表达式里的当前输入，也就是点号 . 所代表的值。例如查询 .name 时，Run(map[string]any{"name": "Ada"}) 能得到一个名字。但 inputs 是另一种读取方式，它需要从编译时配置的 Iter 中不断取值，不能把同一个参数隐式转换成流。

分开设计有两个实际好处：

• 同一个编译后的 Code 可以用不同主输入运行，而额外输入流的来源仍由编译选项控制。
• 调用方必须明确哪些数据进入当前查询、哪些数据允许被 input/inputs 消费，避免隐式读取外部数据。

因此，遇到“inputs 没有读到值”的问题时，先检查三个位置：查询是否真的使用了 input 或 inputs，编译时是否传入 WithInputIter，以及 Run 是否按预期提供了主输入。不要只盯着 Run 的参数。

Iter.Next 的结束和错误要分开处理

gojq 的 Iter 接口很小：Next() (any, bool)。第二个返回值为 false 时表示没有更多项；当它为 true 时，第一个返回值可能是普通结果，也可能是一个 error。这也是 gojq 没有采用常见的 (value, error) 形式的原因之一：一次查询可能产生多个结果和多个错误。

处理结果时建议保持下面的判断顺序：先看 ok 是否为 false，再判断返回值是不是错误。这样不会把正常结束当成业务错误，也不会漏掉迭代中途产生的错误：

for {
    // 每次调用只消费一个结果项，直到迭代器明确结束。
    value, ok := iter.Next()
    if !ok {
        break
    }

    // gojq 允许错误作为结果项出现，因此不能只打印非 error 值。
    if err, ok := value.(error); ok {
        log.Printf("query item failed: %v", err)
        continue // 是否终止由调用方决定；这里选择继续消费后续项。
    }

    fmt.Printf("result=%v\n", value)
}

如果查询中使用了 halt 或 halt_error，还要按 gojq 文档的建议识别 *gojq.HaltError。当它携带的值为 nil 时，可以结束当前处理；普通错误则应根据业务决定记录、返回还是继续。

把固定列表换成自己的输入源

生产代码通常不会把所有对象写在 NewIter 参数里。此时可以实现最小的 Iter 接口，把数据库分页、文件解码器或消息批次包装成“每次返回一项”的数据源。下面用切片演示接口形状，真实项目可把 Next 内部替换为读取逻辑：

type sliceIter struct {
    // values 保存尚未交给 gojq 的输入项。
    values []any
    index  int
}

func (it *sliceIter) Next() (any, bool) {
    // 到达末尾后必须稳定返回 false，避免 input/inputs 无法结束。
    if it.index >= len(it.values) {
        return nil, false
    }
    value := it.values[it.index]
    it.index++ // 只有成功取出一项才推进游标。
    return value, true
}

// 编译时传入：gojq.WithInputIter(&sliceIter{values: source})

自定义迭代器的关键不是复杂的并发技巧，而是明确三件事：没有数据时怎样表示结束，读取失败时怎样把 error 作为迭代项返回，以及底层资源由谁关闭。如果 Next 背后连接文件或网络，建议由创建数据源的业务层负责关闭资源，不要把关闭动作藏在 gojq 查询表达式里。

常见问题

只用 . 过滤数据时需要 WithInputIter 吗？

不需要。只要查询不使用 input 或 inputs，直接把主对象传给 Run 即可。

WithInputIter 能替代 Run 的主输入吗？

不能。它只为 input/inputs 提供额外迭代器；查询当前输入仍由 Run 或 RunWithContext 的参数决定。

为什么 Iter.Next 的第二个返回值不是 error？

因为 gojq 的一次查询可能产生多个结果和多个错误，错误本身可以作为一项返回。第二个布尔值只表示迭代器是否还有项目。

小结

gojq 的 input/inputs 需要单独的输入迭代器，是为了把主查询对象与额外输入流明确分离。固定数据可用 gojq.NewIter，动态数据可实现 Iter.Next；消费结果时同时处理普通值、错误项和结束标志，就能把这条输入通道稳定地嵌入 Go 程序。