Go jsontext Decoder SkipValue 怎样跳过大字段而不保留完整内容

处理大型 JSON 流时，最容易被忽略的是“我不需要这个字段”并不等于“可以先把它读进内存再丢掉”。jsontext.Decoder.SkipValue 的用途就是推进到下一个字段，同时不为了保存整个对象或数组创建一个完整的 Value。需要保留的字段用 ReadValue，不需要的字段用 SkipValue，这是本文的核心分界。

官方文档：https://pkg.go.dev/encoding/json/jsontext

如果字段值可能很大、但当前业务只关心字段名或少数轻量字段，先读字段名，再对该值调用 SkipValue；不要用 ReadValue 读取后再丢弃。

ReadValue 和 SkipValue 的差别在哪里

jsontext 处理的是 JSON 语法层，不负责把数据直接映射成业务结构体。ReadValue 返回一段代表完整 JSON 值的原始字节，标量、对象和数组都可以成为一个值；当目标是几十 MB 的数组或嵌套对象时，这个返回值会把完整内容交给调用方保存。

SkipValue 的语义相当于“读取并丢弃”，但实现不会为了返回完整结果而保留整块值。对于对象或数组，它会继续读取内部 token，直到回到调用前的深度；对于字符串、数字和布尔值等标量，则消费当前值。它仍然会解析并检查 JSON 结构，所以不是跳过字节后就完全不关心语法。

在对象字段循环中选择跳过分支

对象读取的关键顺序是：读取开始对象 token，读取字段名，再决定读取字段值还是跳过字段值。字段名本身是字符串 token，Token.String() 返回去掉 JSON 转义后的字符串值，因此可以直接与业务字段名比较。

package main

import (
    "fmt"
    "strings"

    "encoding/json/jsontext"
)

func readSelectedFields(input string) error {
    dec := jsontext.NewDecoder(strings.NewReader(input))

    // 先确认顶层是对象，后续循环才能按“字段名 + 字段值”读取。
    start, err := dec.ReadToken()
    if err != nil {
        return fmt.Errorf("读取对象开始标记失败: %w", err)
    }
    if start.Kind() != jsontext.KindBeginObject {
        return fmt.Errorf("期望 JSON 对象，实际是 %s", start.Kind())
    }

    for dec.PeekKind() != jsontext.KindEndObject {
        // 对象成员的名字必须先被消费，才能决定如何处理后面的值。
        name, err := dec.ReadToken()
        if err != nil {
            return fmt.Errorf("读取字段名失败: %w", err)
        }
        if name.Kind() != jsontext.KindString {
            return fmt.Errorf("对象字段名不是字符串: %s", name.Kind())
        }

        if name.String() == "payload" {
            // 大对象或大数组只需要跳过，不把完整 Value 留在内存中。
            if err := dec.SkipValue(); err != nil {
                return fmt.Errorf("跳过 payload 失败: %w", err)
            }
            continue
        }

        // 轻量字段需要交给业务逻辑时，再保留它的原始 Value。
        value, err := dec.ReadValue()
        if err != nil {
            return fmt.Errorf("读取 %q 的值失败: %w", name.String(), err)
        }
        fmt.Printf("保留字段 %s: %s\n", name.String(), value.String())
    }

    // 结束标记也要消费，确保对象边界完整闭合。
    if _, err := dec.ReadToken(); err != nil {
        return fmt.Errorf("读取对象结束标记失败: %w", err)
    }
    return nil
}

func main() {
    // payload 可以替换成很大的嵌套对象，示例只保留轻量字段。
    input := `{"id":42,"payload":{"items":[1,2,3]},"kind":"event"}`
    if err := readSelectedFields(input); err != nil {
        panic(err)
    }
}

这段代码的重点不是把所有字段都解析出来，而是把字段筛选放在值读取之前。调用 SkipValue 后，解码器已经位于下一个成员需要的位置，下一轮循环仍然可以继续读取字段名。

嵌套对象、数组和错误应该怎么处理

跳过字段值并不要求调用方自己维护嵌套层级。遇到 { 或 [ 时，SkipValue 会继续读取 token，直到对应深度恢复；标量则按一个值消费。正因为它仍然在维护解码器状态，所以截断的数组、缺少结束标记的对象或底层 Reader 返回错误时，调用仍然会返回错误。

有三个边界要记住：

• 字段名已经读出、字段值尚未读出时才能选择跳过；不要对已经消费完的值再次调用。
• 如果下一个位置已经是对象或数组结束 token，调用 SkipValue 没有可跳过的值，应保留错误并结束当前处理。
• 如果仍需保留原始 JSON，使用 ReadValue，并在下一次读取前完成复制或处理；不要把依赖解码器内部缓冲区的结果长期存放。

用指标判断是否值得改成 SkipValue

这个优化的收益应通过可复现指标判断，而不是只看代码行数。可以准备两条基准路径：一条对目标字段调用 ReadValue 后丢弃，另一条调用 SkipValue。两条路径使用同一份输入、同一组字段筛选和同一轮迭代次数，比较每次操作的分配次数、峰值内存和处理吞吐。

func BenchmarkSkipPayload(b *testing.B) {
    // 基准输入应固定结构，让两条路径只差在值处理方式。
    input := []byte(`{"id":42,"payload":{"items":[1,2,3]},"kind":"event"}`)
    b.ReportAllocs()
    for i := 0; i 

上面的片段是指标设计骨架，正式基准应补齐对象开始标记、字段名和结束标记的消费，并建立对应的 ReadValue 版本。不要把一次本地运行的数字写成所有环境都成立的结论：输入大小、Reader 类型、Go 版本和字段位置都会影响结果。稳定的判断标准是：无须保留值时，SkipValue 是否减少了不必要的分配，同时仍能正确抵达下一个字段。

相关问题

SkipValue 会不会绕过 JSON 语法错误？不会。它仍需读取 token 并维护对象、数组深度，截断或结构不完整时会返回错误。

所有字段都应该用 SkipValue 吗？不是。需要原始 JSON 或需要进一步解码的字段，应使用 ReadValue；只有明确不需要内容的值才跳过。

SkipValue 适合把 JSON 字段删掉后重新编码吗？它适合流式消费时忽略字段；如果要生成新的 JSON，还需要配合 Encoder 写出保留的字段和对应值。