Go jsontext 怎样把大对象拆成逐字段处理

Go jsontext 可以把顶层大对象拆成字段名和字段值：先读取对象起始 token，循环读取字段名，需要的字段用 ReadValue 交给同步回调，不需要的字段用 SkipValue，最后消费对象结束 token。这样不必先把整个对象解码成 map，但单个字段仍可能很大，不能据此承诺固定内存。

先确定版本和要保护的资源

例如某个导入入口接收一个包含多个业务字段的大对象，服务只需要部分字段。若先读完整输入，再解码全部字段，原始字节与业务对象可能同时驻留。这里要减少的是不必要的整对象持有，而不是改变 JSON 的业务含义。

Go 官方在2026年11月发布的介绍确认，encoding/json/jsontext 已随 Go 1.27 正式提供。下面示例面向 Go 1.27，不沿用早期实验版启用方式；旧工具链应查对应版本文档。

官方介绍：https://go.dev/blog/jsonv2

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

对于外部输入，需要同时考虑总输入大小、字段数量、单字段大小和处理耗时。逐字段消费只是资源管理的一部分；若上游已经把完整请求放入字节切片，解码层再流式读取也不能消除那份上游副本。

逐字段读取，同时跳过不需要的值

将以下内容保存为 main.go。代码只接受一个顶层对象，示例过滤 debug 字段，其余字段同步输出名称和原始 JSON 字节长度。它不建立完整结果 map，也不把字段正文写入日志。

package main

import (
    "encoding/json/jsontext"
    "errors"
    "fmt"
    "io"
    "os"
    "strings"
)

// VisitObject 只接受一个顶层对象；回调须同步消费当前值。
func VisitObject(r io.Reader, want func(string) bool,
    consume func(string, jsontext.Value) error) error {
    d := jsontext.NewDecoder(r)
    start, err := d.ReadToken()
    if err != nil {
        return fmt.Errorf("读取对象开头: %w", err)
    }
    if start.Kind() != '{' {
        return errors.New("顶层必须是对象")
    }
    for d.PeekKind() != '}' {
        token, err := d.ReadToken()
        if err != nil {
            return fmt.Errorf("读取字段名，偏移%d: %w", d.InputOffset(), err)
        }
        if token.Kind() != '"' {
            return errors.New("字段名必须是字符串")
        }
        // 独立持有名称，避免依赖后续读取中的临时数据。
        name := strings.Clone(token.String())
        if !want(name) {
            if err := d.SkipValue(); err != nil {
                return fmt.Errorf("跳过字段%q: %w", name, err)
            }
            continue
        }
        value, err := d.ReadValue()
        if err != nil {
            return fmt.Errorf("读取字段%q: %w", name, err)
        }
        // value 是借用缓冲；回调返回前用完，不可直接交给异步任务。
        if err := consume(name, value); err != nil {
            return fmt.Errorf("处理字段%q: %w", name, err)
        }
    }
    if _, err := d.ReadToken(); err != nil {
        return fmt.Errorf("读取对象结尾: %w", err)
    }
    // 此入口只允许一个文档，拒绝尾随第二个值或非法内容。
    _, err = d.ReadToken()
    if errors.Is(err, io.EOF) {
        return nil
    }
    if err != nil {
        return fmt.Errorf("对象尾部: %w", err)
    }
    return errors.New("对象后还有额外JSON值")
}

func main() {
    err := VisitObject(os.Stdin,
        func(name string) bool { return name != "debug" },
        func(name string, value jsontext.Value) error {
            // 示例只输出名称与字节数，不把原始字段写入日志。
            _, err := fmt.Printf("%s: %d bytes\n", name, len(value))
            return err
        })
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

在 Go 1.27 工具链下，可用下面的输入试运行：

# 示例包含普通字段、嵌套对象和被跳过的字段。
printf '%s' '{"record":{"id":7},"label":"oak","debug":[1,2]}' | go run main.go

按示例逻辑应只出现 record 与 label 的记录，不出现 debug；具体字节数取决于输入字段的原始表示。这里说明预期行为，不把示例输出当作已经执行的测量记录。

ReadValue 对嵌套对象或数组读取的是完整字段值，因此外层循环不会把嵌套字段误当成顶层成员。若字段本身是一条很长的数组，应再为该字段设计元素级消费，而不是把外层循环当成所有层次都已流式处理。

借用缓冲不能直接留给异步任务

官方文档说明，ReadValue 返回的数据只在下一次 Peek、Read 或 Skip 调用前有效，解码器使用期间也不能随意修改它。示例要求 consume 在返回之前完成消费，正是为了限定这段借用关系。

若确实要跨调用保存数据，需要先创建独立副本，再明确由谁释放其引用。复制可以解决生命周期问题，却会增加内存持有；把所有副本放进切片或无界任务集合，会重新积累出接近整份输入的数据量。

SkipValue 适合忽略完整值。它仍需要扫描输入并识别合法结构，不意味着可以零成本跳过任意长度数据。不要为了节约内存就忽略其错误，否则后续字段位置和内容完整性都失去依据。

把单个大字段和下游积压纳入资源预算

这套实现让应用层通常只处理当前字段，但解码缓冲的容量、对象名称记录、当前字段、独立副本和下游队列都可能占用内存。尤其一个字段就容纳大数组或大字符串时，“逐字段”仍可能需要大量缓冲；不能把峰值写成严格等于一个小字段。

对服务入口设置总量约束时，还要区分真实文件结束与人为截断。仅把 Reader 截成某个长度，可能把后续额外内容藏在限额之外；应由入口层明确报告超限，而不是把截断后的 EOF 当成完整文档结束。网络超时和取消也应在来源及下游操作中落实，解码器不会自动替业务系统管理这些资源。

错误记录与完成条件

示例在读取字段名出错时附带 InputOffset。该值表示最近返回的 token 或值之后的位置，并不等同于底层 Reader 已读取的总字节数。日志可以记录处理阶段、受控的字段标识、偏移和错误类型；真实字段名也可能含敏感信息，不宜无条件照搬示例的明文日志策略。

逐字段回调可能在后续语法错误发生前已经产生副作用。如果业务要求整份文档全成或全败，应使用暂存、事务或可回退安排，完整读取及尾部检查成功后再提交。不要把前几个字段成功当作整份对象成功。

接入自己的环境时，可准备空对象、嵌套值、被跳过字段、输入截断和尾随第二个值等样本，观察其完成或失败路径。需要比较内存时，使用相同输入、相同业务消费和相同工具链测量，同时观察下游是否偷偷保存了所有值。没有测量数据时，只讨论持有方式，不宣称节省某个百分比。

常见问题

能否用 ReadValue 一次读完整个对象？

可以读取一个完整值，但这样会回到整对象持有的方向。要拆成字段，必须先进入对象，再按名称和值处理。

PeekKind 出错会不会造成死循环？

示例随后调用 ReadToken，读取错误会返回，因此不会只反复 Peek 而不消费或处理错误。不要删掉读取阶段的错误分支。

对象结束后为什么还读一次？

该入口只接受一个文档。结束后继续读取用于拒绝尾随第二个值或非法内容；若协议允许多个顶层值，应另行设计文档循环。

换成逐字段处理就一定比 map 更省内存吗？

不一定。上游缓冲、最大字段、名称数量和下游持有方式都会影响结果。它提供更细的消费边界，实际收益仍由具体负载决定。