Go encoding/json/jsontext 怎样读取 JSON token

如果你只想知道一份 JSON 里有哪些字段、数组嵌套到哪一层，或者需要在读到目标字段后跳过一整段值，直接把数据反序列化成结构体往往太重。Go 1.27 提供的 encoding/json/jsontext 面向 JSON 语法本身，Decoder 可以把输入读取为连续的 Token。

官方资料：https://pkg.go.dev/encoding/json/jsontext

它适合做语法级扫描、结构检查、选择性读取和 JSON 转换。本文只讨论 token 流读取和对象、数组边界，不把它当成结构体反序列化器。

jsontext 的 Token 到底表示什么

jsontext.Token 是 JSON 词法层的一个最小单位，可以表示 null、true、false、字符串、数字，以及对象和数组的开始、结束分隔符。对象中的冒号、成员之间的逗号不会单独变成 Token，因为它们可以由当前结构推断出来。

因此，下面这段 JSON 的 token 序列可以理解为：对象开始、成员名、字符串值、另一个成员名、数组开始、数字值、数组结束、对象结束。成员名和成员值之间的冒号是语法关系，不需要额外读取一个 token。

{
  "name": "go",
  "items": [1]
}

这和传统的 encoding/json.Decoder.Token 思路相近，但 jsontext 是独立的语法处理包，并且提供了配套的 PeekKind、SkipValue、ReadValue 等更底层操作。需要把 JSON 解释成业务对象时，仍然应该优先考虑结构体反序列化。

用 ReadToken 顺序读完整个输入

最小读取程序只需要一个 io.Reader、一个 jsontext.Decoder 和一个循环。遇到 io.EOF 代表输入已经读完，其他错误则应立即返回，因为它可能表示 JSON 语法不完整。

package main

import (
    "fmt"
    "io"
    "strings"

    "encoding/json/jsontext"
)

func main() {
    input := strings.NewReader(`{"name":"go","items":[1,2]}`)
    dec := jsontext.NewDecoder(input)

    for {
        tok, err := dec.ReadToken()
        if err == io.EOF {
            // EOF 只表示没有更多 token，不是读取失败。
            break
        }
        if err != nil {
            // 语法错误要停止处理，避免把后续 token 当成可靠数据。
            panic(err)
        }

        // Kind 用来区分边界、字符串、数字和字面量等 token 类型。
        fmt.Printf("kind=%q raw=%s\n", tok.Kind(), tok.String())
    }
}

Token.Kind() 适合做分支，Token.String() 则返回字符串 token 的非转义值，其他类型返回原始 JSON 表示。对于对象和数组的开始、结束边界，直接比较 kind 就能判断层级变化。

用开始和结束 token 维护结构层级

读取 token 时，建议把结构边界当作一张轻量的栈：看到 { 就进入对象，看到 [ 就进入数组；看到对应的结束 token 就退出。这样做不需要把整个 JSON 放入 map[string]any，也能知道当前 token 位于哪一层。

package main

import (
    "fmt"
    "io"
    "strings"

    "encoding/json/jsontext"
)

func main() {
    dec := jsontext.NewDecoder(strings.NewReader(`{"user":{"name":"go"},"ids":[10,20]}`))
    depth := 0

    for {
        tok, err := dec.ReadToken()
        if err == io.EOF {
            break
        }
        if err != nil {
            panic(err)
        }

        switch tok.Kind() {
        case '{', '[':
            // 开始分隔符进入一层，先打印旧层级再递增。
            fmt.Printf("depth=%d open=%s\n", depth, tok.String())
            depth++
        case '}', ']':
            // 结束分隔符退出一层，避免把结束边界算到下一层。
            depth--
            fmt.Printf("depth=%d close=%s\n", depth, tok.String())
        default:
            // 字符串、数字和字面量都属于当前容器的内容。
            fmt.Printf("depth=%d value=%s\n", depth, tok.String())
        }
    }
}

这个例子只跟踪深度，并没有判断对象成员名。实际扫描对象时，可以根据当前位置把字符串 token 解释为成员名，再把紧随其后的 token 解释为对应值；冒号和逗号仍由 JSON 结构隐含。

只关心一部分字段时先看类型再跳过值

当 JSON 中有很大的嵌套对象，而当前任务只关心少数成员时，不必先把整棵值读到内存。PeekKind 可以查看当前位置的 kind，SkipValue 可以跳过当前位置对应的完整 JSON 值，包括嵌套对象或数组。

package main

import (
    "fmt"
    "io"
    "strings"

    "encoding/json/jsontext"
)

func main() {
    dec := jsontext.NewDecoder(strings.NewReader(`{"name":"go","profile":{"level":2},"enabled":true}`))

    for {
        tok, err := dec.ReadToken()
        if err == io.EOF {
            break
        }
        if err != nil {
            panic(err)
        }
        if tok.Kind() != '"' || tok.String() != "name" {
            // 非目标成员名后面紧跟一个值，交给 SkipValue 一次跳过。
            if err := dec.SkipValue(); err != nil {
                panic(err)
            }
            continue
        }

        kind, err := dec.PeekKind()
        if err != nil {
            panic(err)
        }
        if kind != '"' {
            // 类型不符合预期时跳过，避免把数字误当字符串读取。
            if err := dec.SkipValue(); err != nil {
                panic(err)
            }
            continue
        }
        value, err := dec.ReadToken()
        if err != nil {
            panic(err)
        }
        fmt.Println("name=", value.String())
    }
}

示例的重点是读取位置：读完成员名后，游标位于成员值之前，所以此时调用 PeekKind 或 SkipValue 才有意义。跳过值之后，下一次读取会落到下一个成员名或容器结束边界。

Token 有效期很短，保存前要先 Clone

从 ReadToken 得到的 token 可能引用 Decoder 内部缓冲区。官方文档规定，下一次对同一个 Decoder 调用方法后，这个 token 就不再保证有效。如果需要把它放进切片、跨函数保存或延后处理，应调用 Clone 拿到独立副本。

tok, err := dec.ReadToken()
if err != nil {
    return err
}

saved := tok.Clone()
// saved 不再依赖 Decoder 的下一次读取，可以交给后续处理。
_ = saved

如果你需要的是一个完整的对象或数组原文，而不是逐个 token，可以考虑 ReadValue。它返回的是完整 JSON 值的原始字节，适合把某个子树原样转交给其他解析逻辑。

按任务选择 Token、Value 还是结构体

采用前重点记住三件事：第一，逗号和冒号不是独立 Token；第二，结束 token 是层级判断的关键；第三，读取到的 Token 不要跨过下一次 Decoder 调用长期持有。只要任务是语法扫描或选择性跳过，jsontext.Decoder 就能把 JSON 处理拆成可控的小步；一旦进入业务字段映射，及时回到结构体语义解析。

常见相关问题

jsontext.Token 能代表整个对象吗？

不能。Token 只能表示一个词法单位，完整对象或数组应该使用 jsontext.Value，或者继续读取其内部 token。

为什么没有逗号和冒号 token？

它们由 JSON 语法和当前结构推断出来。对象成员名后面必须是成员值，数组元素之间也不需要额外的分隔 token。

读到 Token 后能不能一直保存它？

不要直接保存从 Decoder 读取的 token。下一次 Decoder 方法调用可能使它失效，需要长期保存时先调用 Clone。

jsontext 能替代所有 JSON 反序列化吗？

不能。它解决的是 JSON 语法层的流式处理；业务对象映射、字段校验和默认值处理仍适合交给结构体和语义层 API。