Go json/v2 UnmarshalRead 怎样在从 Reader 解码 JSON（输入边界）

一次接口改造后，服务端把旧的字节切片解码改成了 encoding/json/v2.UnmarshalRead。代码看起来更贴近 HTTP 请求体，单个对象也能正常落到结构体里；但当上游把两个 JSON 对象连续写进同一个 Reader 时，接口突然返回了解码错误。

这次故障的根因不是 Reader “读得太快”，而是对 API 契约的理解少了一半：UnmarshalRead 不是“读出第一个 JSON 值就返回”，它要求 Reader 中最终只有一个完整 JSON 值，并继续读到 io.EOF。因此，单对象请求体适合它，JSON 多值流则应该换成显式的流式解码 API。

记住一句话：UnmarshalRead 负责“一个 Reader 里的一个 JSON 值”，并把 Reader 的结束当作输入边界的一部分。

问题现场：请求体为什么在尾随内容处失败

先把现场缩小成一个输入契约。假设目标结构体只需要 id 和 name，请求体应该是一个 JSON 对象，前后可以有空白，但不应该在第一个对象后再接第二个对象：

{"id": 17, "name": "gopher"}

下面这个写法直接把 HTTP 请求体交给 UnmarshalRead。r.Body 本身就是 io.Reader，调用方只需要传入一个非空指针作为解码目标。

package main

import (
	"encoding/json/v2"
	"fmt"
	"net/http"
)

type createRequest struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

func handleCreate(w http.ResponseWriter, r *http.Request) {
	var req createRequest
	// UnmarshalRead 会把请求体当作一个完整 JSON 值读取到 EOF。
	if err := json.UnmarshalRead(r.Body, &req); err != nil {
		// 解码失败时先返回错误，不把未完成的结构体交给业务层。
		http.Error(w, "invalid JSON body", http.StatusBadRequest)
		return
	}

	// 只有完整解码成功后，才进入创建逻辑。
	fmt.Fprintf(w, "created %d:%s", req.ID, req.Name)
}

如果输入是 {"id":17}{"id":18}，第一眼容易认为“第一个对象已经读完，应该可以返回”。但 UnmarshalRead 的语义还包括继续确认 Reader 是否正常结束；尾随的第二个值不是允许忽略的垃圾，而是说明这次输入不符合“单个 JSON 值”的契约。

触发条件：EOF、空输入和语义错误不是一回事

排查这类问题时，我会先把错误分成三组，而不是看到“decode failed”就统一重试。

空白不是尾随业务数据。单个 JSON 值之后的空格、换行属于 JSON 文本允许的间隔，真正需要警惕的是第二个值、不可识别字符，或把一段本来应该分帧的数据当成一个请求体。

还要注意目标参数：不能把普通变量的值传进去，也不能传入 nil 指针。调用应当让解码器有一个可以写入的非空指针，例如 &req。如果目标是 any，最好先明确希望得到的具体类型；否则数字、对象等值的语义可能不是业务真正想要的结果。

修复动作：把 Reader 边界放在解码前

确认输入确实是“一个请求对应一个 JSON 值”后，修复重点就从解码函数移到了 Reader 边界。HTTP 请求不能无限制地交给解析器，应该先设定一个业务允许的上限，再让 UnmarshalRead 处理被限制后的 Reader。

package main

import (
	"encoding/json/v2"
	"io"
	"net/http"
)

const maxBodyBytes = 1 

这个示例表达的是边界关系，不是让所有接口都固定使用 1 MiB。真实项目还要结合反向代理、网关和业务字段大小设置上限；关键是要让“资源保护”和“JSON 语法解码”各自有清晰职责。

根因复盘：什么时候不该继续使用 UnmarshalRead

如果发送方确实要在同一个 Reader 中连续发送多个 JSON 值，那么问题不在于把 UnmarshalRead 再调用几次。第一次调用已经按“读到 EOF”处理整个 Reader，第二次调用没有可靠的值可读。此时应把输入建模为流，并显式创建 jsontext.Decoder，每次用 UnmarshalDecode 取一个值。

package main

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

func readStream(input string) ([]createRequest, error) {
	dec := jsontext.NewDecoder(strings.NewReader(input))
	var result []createRequest
	for {
		var item createRequest
		// UnmarshalDecode 只处理流中的下一个 JSON 值。
		err := json.UnmarshalDecode(dec, &item)
		if err == io.EOF {
			// EOF 在这里表示流已经自然结束。
			return result, nil
		}
		if err != nil {
			// 当前值有语法或语义问题时停止继续消费。
			return nil, err
		}
		result = append(result, item)
	}
}

两套 API 的差别可以这样记：面向 HTTP JSON 请求、配置文件或单个消息时，UnmarshalRead 让 Reader 的结束成为完整性检查的一部分；面向日志拼接、批量消息或 whitespace-delimited JSON 时，使用 jsontext.Decoder 和 UnmarshalDecode，由调用方决定每个值如何消费。

迁移到 encoding/json/v2 还要单独留意行为变化。Go 1.27 的官方说明提到，v2 默认拒绝无效 UTF-8 和对象重复名称，字段名匹配也更严格；旧项目不能只把 import 路径替换掉就认为兼容性完成。本文只解决 Reader 的单值边界，其他 v1/v2 语义应按项目测试逐项确认。

防复发清单：发布前把这五项写进复查

1. 确认一个请求体是否只承载一个 JSON 值；如果是多值流，不使用 UnmarshalRead 伪装成循环读取。
2. 确认目标参数是可写入的非空指针，并为关键字段使用明确的 Go 类型。
3. 在 Reader 外层设置合理的输入上限，避免把资源保护责任全部交给 JSON 解码器。
4. 把“输入不完整”“尾随内容”“字段语义不匹配”分别记录，便于区分上游协议问题与模型问题。
5. Go 1.27 迁移时补充重复字段、字段大小写、无效 UTF-8 和空切片/空映射等 v2 行为回归用例。

最后回到标题的问题：Go json/v2 的 UnmarshalRead 用法并不复杂，真正容易出错的是把它当成“只拿第一个 JSON 值的 Reader 版 Unmarshal”。只要先确定输入是单值，再设置 Reader 上限并检查完整错误边界，它就很适合处理 HTTP 请求体；如果输入天然是多值流，就让 UnmarshalDecode 接管消费节奏。

相关问题

UnmarshalRead 能否接收 bytes.Buffer？

可以。只要对象实现 io.Reader，例如 bytes.Buffer、文件或 HTTP 请求体，都可以作为输入；仍然需要遵守单个 JSON 值和读到 EOF 的契约。

为什么不直接忽略 JSON 后面的内容？

因为请求体的边界通常也是协议完整性的检查点。若业务允许多个值，应显式使用流式 API；静默忽略尾随内容容易把拼接错误或错误分帧隐藏起来。