Go encoding/json/v2 怎样从 Reader 解码多个值

如果输入来自文件、HTTP 请求体或消息管道，开发中经常会遇到这样的内容：同一个 io.Reader 里连续放着多个 JSON 对象，中间只用空白分隔。encoding/json/v2 可以处理这种输入，但入口不能选错：UnmarshalRead 面向一个顶层 JSON 值；真正的多值流读取，应交给 jsontext.Decoder，再用 UnmarshalDecode 一次取一个值。

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

想从 Reader 读取多个顶层 JSON 值，就把 Reader 包装成 jsontext.Decoder，循环调用 json.UnmarshalDecode；只有 io.EOF 表示流正常结束，其它错误都应该保留并处理。

先把单值 API 和多值流分开

UnmarshalRead 的职责是从 io.Reader 解码一个 JSON 值。官方文档还特别说明，它会继续读取 Reader，直到遇到 io.EOF，以便确认顶层值之后没有意外的额外字节。因此它适合 HTTP 请求体中的单个对象，也适合一个完整的 JSON 数组，但不是连续对象流的循环入口。

下面这个输入包含两个顶层对象：

{"id":1,"kind":"start"}
{"id":2,"kind":"finish"}

如果把它交给 UnmarshalRead，第一个对象虽然能够被识别，但后面的第二个顶层值不再符合“单个 JSON 值”的契约，调用最终会返回错误。这里的问题不是 Reader 不能继续读，而是 API 选择明确要求一个顶层值。

用 jsontext.Decoder 保留顶层值边界

多值流的关键是先创建 jsontext.Decoder。它负责从 Reader 中识别下一个顶层 JSON 值，并在值与值之间处理允许的空白。encoding/json/v2 负责把识别出的值映射到 Go 结构体；两层职责分别是语法读取和语义解码。

当前工具链使用 encoding/json/v2 时，还要按对应版本的要求启用 jsonv2 实验能力。下面的示例把每个对象解码成同一个 Event 类型：

//go:build goexperiment.jsonv2

package main

import (
	"encoding/json/jsontext"
	jsonv2 "encoding/json/v2"
	"fmt"
	"io"
	"strings"
)

type Event struct {
	ID   int    `json:"id"`
	Kind string `json:"kind"`
}

func main() {
	// 两个对象是同一个 Reader 中的两个顶层 JSON 值。
	const input = `{"id":1,"kind":"start"}
{"id":2,"kind":"finish"}`

	dec := jsontext.NewDecoder(strings.NewReader(input))
	for {
		var event Event
		// 每次只取下一个顶层值，并写入当前目标结构体。
		err := jsonv2.UnmarshalDecode(dec, &event)
		if err == io.EOF {
			// 空白之后没有下一个值，表示流正常结束。
			break
		}
		if err != nil {
			// 语法错误或目标类型不匹配不能当作正常结束。
			panic(err)
		}
		fmt.Printf("%d %s\n", event.ID, event.Kind)
	}
}

循环里每一轮都重新声明 event，这样一个值的字段不会因为复用目标对象而残留到下一个值。若目标结构体较大，也可以复用同一个变量，但要明确 v2 对对象解码的合并语义，并在业务需要时主动清理字段。

循环解码时只把 io.EOF 当作正常结束

UnmarshalDecode 的多值语义很适合这种循环：还有值时返回 nil，没有更多顶层值时返回 io.EOF。因此判断顺序应该是先处理 EOF，再处理其它错误，不能用“任意错误都代表结束”的写法。

例如输入尾部被截断时，解码器返回的可能是语法错误或意外结束错误；这说明数据不完整，应该记录上下文、丢弃当前消息或交给上层重试。只有输入完整地走到末尾，才把 io.EOF 当作结束条件。

//go:build goexperiment.jsonv2

package stream

import (
	"encoding/json/jsontext"
	jsonv2 "encoding/json/v2"
	"errors"
	"io"
)

type Event struct {
	ID int `json:"id"`
}

func readEvents(r io.Reader, handle func(Event) error) error {
	// Decoder 保留 Reader 中每个顶层值的边界，不把整条流一次读入内存。
	dec := jsontext.NewDecoder(r)
	for {
		var event Event
		if err := jsonv2.UnmarshalDecode(dec, &event); err != nil {
			if errors.Is(err, io.EOF) {
				// 正常读到流尾，调用方无需把 EOF 当作业务失败。
				return nil
			}
			// 非 EOF 错误保留给调用方，便于记录坏数据位置或重试。
			return err
		}
		if err := handle(event); err != nil {
			// 业务处理失败不应被下一轮解码掩盖。
			return err
		}
	}
}

数组、空白和坏数据要分别判断

多值流和 JSON 数组不是同一种输入格式。下面的数组只有一个顶层值，UnmarshalRead 直接解码到切片更自然：

//go:build goexperiment.jsonv2

package main

import (
	jsonv2 "encoding/json/v2"
	"strings"
)

type Event struct {
	ID int `json:"id"`
}

func readArray() ([]Event, error) {
	// 方括号把多个元素包成一个顶层 JSON 数组。
	const input = `[{"id":1},{"id":2}]`
	var events []Event
	// 单值 API 读取的是整个数组，而不是数组中的多个顶层值。
	if err := jsonv2.UnmarshalRead(strings.NewReader(input), &events); err != nil {
		return nil, err
	}
	return events, nil
}

相反，连续对象之间只允许空白时，应使用前面的 Decoder 循环。尾部空白属于正常情况；夹在值之间的非 JSON 内容、截断的字符串、字段类型不匹配，都应继续向上返回错误。不要为了“让批处理跑完”而忽略这些错误，否则很难区分真实的流结束与数据损坏。

按输入形态选择 API

这也是一个值得保留在代码评审里的判断：如果协议能控制，数组通常更容易描述总数和整体失败；如果输入是持续到达的记录流，或者不希望把所有对象一次装进内存，Decoder 循环更贴合 Reader 的边界。

常见问题

UnmarshalRead 能不能在循环里反复调用？

不建议。它每次都把传入 Reader 当作一个完整顶层值来读取，并检查后续内容；多值流应让同一个 Decoder 维护读取状态。

为什么 io.EOF 不能直接当成所有错误的结束标志？

EOF 表示没有下一个顶层值，坏 JSON 或目标类型不匹配则代表输入或数据语义有问题。把两者混在一起会吞掉损坏记录。

多个对象之间必须换行吗？

不必须。只要顶层值之间有 JSON 允许的空白，空格、换行或制表符都可以；换行只是日志和 JSON Lines 场景中更便于观察的格式。

UnmarshalDecode 会不会一次把整个 Reader 读进内存？

它通过 jsontext.Decoder 按顶层值推进，适合流式处理；但单个 JSON 值本身仍需要被读取和解码，不能把它理解成对任意超大对象都零内存。

总结起来，标题中的“从 Reader 解码多个值”真正对应的是两层 API 的配合：jsontext.Decoder 负责找出下一个顶层值，UnmarshalDecode 负责把它变成 Go 数据；循环只在 io.EOF 时结束，其它错误都应保留。