Go jsontext Decoder PeekKind 怎样判断下一个 token 类型

在流式解析 JSON 时，很多分支并不需要立刻把下一个值读出来：看到对象开始就进入对象处理，看到结束标记就收层级，看到标量才读取内容。jsontext.Decoder.PeekKind() 正好用于这个判断：它查看下一个 token 的类型，但不会推进读取偏移。真正消费数据仍要调用 ReadToken、ReadValue 或 SkipValue。

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

把 PeekKind 当作“看一眼下一项”的观察接口，而不是读取接口。它返回 KindInvalid 时不要直接当成 EOF；应继续调用一次读取方法，让缓存的错误通过正常的 error 返回值暴露出来。

PeekKind 只观察类型，不会消费下一个 token

Decoder 维护着 JSON 语法状态。调用 PeekKind 后，下一个 token 仍在原来的位置，后续 ReadToken 或 ReadValue 还会读取同一项。这个特性适合在读取前做轻量分派，例如先区分对象、数组和标量，再选择不同的处理方式。

package main

import (
	"fmt"
	"strings"

	"encoding/json/jsontext"
)

func main() {
	// 先观察输入的首个 token，再用 ReadToken 真正消费它。
	dec := jsontext.NewDecoder(strings.NewReader(`{"id":7}`))
	kind := dec.PeekKind()
	fmt.Println("观察到：", kind)

	// PeekKind 不推进偏移，因此这里仍能读到对象开始标记。
	tok, err := dec.ReadToken()
	if err != nil {
		panic(err)
	}
	fmt.Println("实际读取：", tok.Kind())
}

图中的箭头只表示静态职责关系：PeekKind 产出类型判断，读取偏移仍由后续读取方法推进。不要把它理解为已经完成了一次读取。

根据 Kind 选择 ReadToken、ReadValue 还是 SkipValue

判断出类型后，读取方法要和数据形态匹配。需要保留语法边界时用 ReadToken；要一次取得完整 JSON 值时用 ReadValue；明确不关心某个完整值时用 SkipValue，避免为了丢弃结果而申请整段内存。

func consumeNext(dec *jsontext.Decoder) error {
	// PeekKind 只负责选择分支，不负责推进 Decoder。
	switch kind := dec.PeekKind(); kind {
	case jsontext.KindBeginObject, jsontext.KindBeginArray:
		// 容器值可以整体读取，或改用 ReadToken 逐个处理。
		_, err := dec.ReadValue()
		return err
	case jsontext.KindEndObject, jsontext.KindEndArray:
		// 结束标记是结构 token，必须用 ReadToken 消费。
		_, err := dec.ReadToken()
		return err
	default:
		// 不需要保留当前标量时，用 SkipValue 直接丢弃它。
		return dec.SkipValue()
	}
}

上面的分派是一个最小示意，真实代码还要结合当前容器层级和业务字段判断。对象名通常要用 ReadToken 读取，完整对象或数组才适合交给 ReadValue；不能只根据“看起来像 JSON”就固定调用同一个方法。

KindInvalid、io.EOF 和结束标记不是一回事

PeekKind 没有单独返回 error，发生错误时会返回 KindInvalid，并把错误缓存到 Decoder，直到下一次 read 调用。因而它不是一个可以独立完成错误处理的探针。

• KindInvalid：表示 PeekKind 没能得到有效类型，可能是输入错误或读取错误；继续用 ReadToken、ReadValue 或 SkipValue 获取实际错误。
• io.EOF：由读取方法返回，表示没有更多可读 token 或 value。不要仅凭 KindInvalid 就判定输入结束。
• KindEndObject / KindEndArray：表示当前位置是对象或数组的结束边界。它们是结构 token，应由 ReadToken 消费；对结束标记调用 ReadValue 会得到语法错误，而且状态不会推进。

如果需要记录位置，可以在真正读取前后配合 InputOffset。该偏移表示最近一次成功返回的 token 或 value 之后的位置，底层 Reader 的预读字节不等于已经被 JSON 读取逻辑消费。

常见问题

PeekKind 会推进 InputOffset 吗？

不会。PeekKind 只获取下一个 token 的 Kind；读取偏移要等 ReadToken、ReadValue 或 SkipValue 等 read 调用推进。

KindInvalid 就是 JSON 流结束吗？

不是。KindInvalid 可能来自语法或输入错误，错误会缓存到下一次读取调用。应检查读取方法返回的 error，并用 errors.Is 判断是否为 io.EOF。

为什么看到结束标记还要 ReadToken？

对象和数组的结束标记属于结构 token，不是一个完整 JSON value。先用 PeekKind 观察到结束类型，再用 ReadToken 消费，才能让 Decoder 退出当前嵌套层级。

总结一下：PeekKind 负责不消费的类型判断，ReadToken 负责 token 级读取，ReadValue 负责完整值，SkipValue 负责无保留丢弃。只要把 KindInvalid、io.EOF 和容器结束标记分开处理，流式 JSON 的读取分派就不会被“先看后读”混淆。