Go gojq 迭代器产出的 error 为什么不能当成普通结果

如果你用 Go 把 gojq 当作库嵌入程序，看到 iter.Next() 返回的 any 里出现 error，不要把它直接当成查询结果打印或继续做类型转换。gojq 的迭代器故意把错误作为“结果项”发出，因为一次查询可能产生多个值，也可能在值之间产生多个错误；它的接口不能简单改成只返回一个 error。

官方文档：https://pkg.go.dev/github.com/itchyny/gojq

正确的消费方式是：先判断 ok 是否为真，再判断 v 是否实现 error。ok=false 代表迭代器没有下一项；ok=true 且 v 是 error，代表当前这一项是错误，不是普通业务值。

Next 返回的两个值分别代表什么

gojq.Iter 的核心接口只有 Next() (any, bool)。第一个返回值是当前项，第二个返回值表示当前项是否存在。也就是说，bool 负责“有没有这一项”，而不是负责“这一项是否成功”。

如果接口设计成 (any, error)，调用方通常会把第一个错误当成整个查询结束；但 jq 风格查询可以产生多项输出，gojq 也明确允许迭代器在结束前发出错误。因此错误只能作为当前迭代项，由调用方决定停止、记录还是继续。

在循环里先把 error 分流

最小的消费骨架如下。注意类型断言必须发生在普通值处理之前，否则把错误当成 map[string]any、字符串或数字转换时，真正的问题会被遮住。

package main

import (
    "fmt"
    "log"

    "github.com/itchyny/gojq"
)

func consume(iter gojq.Iter) {
    for {
        // ok 只表示当前是否取到一项，不表示这一项一定成功。
        v, ok := iter.Next()
        if !ok {
            // 没有下一项才是正常的迭代终止。
            return
        }

        // error 也是 gojq 迭代器可能发出的项，必须先分流。
        if err, ok := v.(error); ok {
            // 这里选择停止；需要容错时也可以记录后 continue。
            log.Printf("gojq query item failed: %v", err)
            return
        }

        // 只有确认不是 error 后，才按业务类型处理普通值。
        fmt.Printf("value=%#v\n", v)
    }
}

这个顺序还解决了一个容易混淆的问题：v == nil 不是判断迭代结束的可靠方式。某一项可能本身就是 JSON 的 null，它仍然需要通过 ok=true 被消费；真正的结束条件是 Next 返回 ok=false。

普通错误和 HaltError 要分开处理

并不是所有 error 都应该用同一种策略。普通查询错误通常意味着当前输入或表达式无法得到有效结果，服务可以选择停止并返回错误，也可以记录后继续读取后续项。gojq 不能替你决定业务策略，所以它只把错误放入迭代通道。

HaltError 是需要额外辨认的特殊类型。它对应 jq 的 halt 或 halt_error 语义。文档建议遇到它时停止迭代；当 Value() 返回 nil 时，可以把它理解成“停止但不再处理一个错误值”。一种更稳妥的写法是：

func consumeWithHalt(iter gojq.Iter) error {
    for {
        // 先区分“没有下一项”和“下一项是错误”。
        v, ok := iter.Next()
        if !ok {
            return nil
        }

        if err, ok := v.(error); ok {
            // HaltError 可能携带一个值；Value 为 nil 时直接结束。
            if halt, ok := err.(*gojq.HaltError); ok {
                if halt.Value() == nil {
                    return nil
                }
                return halt
            }
            // 普通 error 交给上层决定是否重试、记录或终止。
            return err
        }

        // 这里才进入普通结果的业务分支。
        _ = v
    }
}

不要把 HaltError 的特殊语义扩展成“所有 error 都可以忽略”。如果业务需要继续，应该明确记录错误并限制后续消费范围；否则一个持续产生错误或无限输出的查询可能让调用方一直循环。

自定义迭代器也遵循同一条规则

通过 WithIterFunction 注册自定义迭代函数，或用 gojq.NewIter 包装多个值时，返回的仍然是 gojq.Iter。因此自定义函数可以把错误作为一项返回，但调用方不能假定它会变成第二个返回值。

func makeIter(input any) gojq.Iter {
    if input == nil {
        // 用 error 作为迭代项，保持与 gojq.Iter 契约一致。
        return gojq.NewIter(fmt.Errorf("input is nil"))
    }

    // 多个值仍然由 Next 逐项提供给调用方。
    return gojq.NewIter("first", "second")
}

如果查询可能无限输出，或自定义迭代器背后连接了外部资源，优先使用 RunWithContext 让上下文承担超时和取消边界。错误分流解决的是“当前项是什么”，上下文解决的是“这次消费最多持续多久”，两者不要混为一谈。

最后记住这三个判断

• ok=false：没有下一项，结束迭代。
• ok=true 且 v 是 error：当前项是错误，按类型和业务策略处理。
• ok=true 且不是 error：才把 v 当作普通查询结果。

相关问题

为什么不直接把 gojq 的错误写成第二个返回值？因为一个查询可能产生多个值，也可能产生多个错误，固定的第二个 error 无法表达每一项的错误位置。

遇到普通 error 能不能继续 Next？可以，但这是调用方的策略；应先记录错误并确认后续结果仍有业务意义，同时为无限查询设置 context 边界。