Go json.Decoder Decode 成功后为什么还要检查尾随内容

json.Decoder.Decode 返回 nil，只表示它成功读取了输入中的下一个 JSON 值，并不表示整个输入流已经结束。对于 HTTP 请求体、配置文件等“只能提交一个顶层 JSON 值”的接口，第一次解码后还要再调用一次 Decode：只有第二次得到 io.EOF，才能确认后面只剩允许的空白字符。

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

Decode 的目标是读取下一个值

Decoder 面向 io.Reader，本来就支持从流里连续读取多个 JSON 值。输入是 {"id":1} {"id":2} 时，第一次 Decode 读取第一个对象后即可成功返回；第二个对象仍留在流中，等待下一次调用。这个行为适合日志流或协议明确允许连续值的场景，却不等于“整个请求体是一个完整且唯一的 JSON”。

因此要先写清接口契约：如果输入允许连续 JSON 值，就循环调用 Decode；如果输入必须恰好一个值，就必须确认首个值之后到达 EOF。

三类尾部结果应该怎样判断

关键不是把第二个值保存下来，而是判断第二次调用的错误是否恰好为 io.EOF。把任意错误都当作“已经结束”会错误地放过垃圾字节；只检查第一次错误则会放过完整的第二个 JSON 值。

封装一个只接受单个 JSON 值的入口

下面的辅助函数把“业务对象解码”和“输入是否结束”分成两个判断。空结构体仅作为第二次读取的接收目标；无论尾部是对象、数组、字符串、数字还是 null，只要结果不是 io.EOF，都按尾随内容处理。

package strictjson

import (
    "encoding/json"
    "errors"
    "fmt"
    "io"
)

func DecodeExactlyOne(r io.Reader, dst any) error {
    dec := json.NewDecoder(r)

    // 可选：业务结构体不接受未声明字段时开启；它不替代尾随检查。
    dec.DisallowUnknownFields()

    // 第一次调用只负责读取并转换首个 JSON 值。
    if err := dec.Decode(dst); err != nil {
        return fmt.Errorf("解析 JSON：%w", err)
    }

    // 第二次调用只探测是否还有内容；只有 EOF 表示后面仅剩空白。
    var extra struct{}
    err := dec.Decode(&extra)
    if errors.Is(err, io.EOF) {
        return nil
    }
    if err == nil {
        return errors.New("输入包含多个 JSON 值")
    }
    return fmt.Errorf("JSON 后存在非法尾随内容：%w", err)
}

这里使用 errors.Is(err, io.EOF) 明确表达结束条件。第二次调用返回 nil，说明确实又读到了一个 JSON 值；返回其他错误，说明尾部存在无法按 JSON 继续解析的内容。两种情况都违反“恰好一个值”的契约。

不要用 More 或 Buffered 代替结束检查

Decoder.More 用来判断当前数组或对象中是否还有元素，不是判断顶层输入流是否结束。对顶层单值请求直接使用它，会混淆容器边界和流边界。

Decoder.Buffered 只返回 Decoder 已经预读但尚未使用的那一部分数据。底层 io.Reader 可能仍有更多内容，因此仅查看缓冲区是否为空也不能证明已经到达输入末尾。让 Decoder 再读取一次，才能把内部缓冲和底层 Reader 一起纳入判断。

严格字段与尾随内容是两种约束

DisallowUnknownFields 解决的是“首个对象里是否出现目标结构体没有的字段”；UseNumber 影响数字解码到接口值时的表示。它们都不会自动把输入限制为一个顶层值。调用方需要分别决定字段策略、数字策略和流结束策略，不能因为首个对象严格解码成功，就省略 EOF 检查。

常见问题

第二次 Decode 会不会把结尾空白当成错误？

不会。JSON 值后的合法空白会被跳过，输入结束时返回 io.EOF，这正是单值契约应接受的结果。

为什么不用 json.Valid 检查整个请求体？

json.Valid 接收完整字节切片，适合数据已经全部在内存中的情况。面对 io.Reader，Decoder 可以直接流式读取；但调用方要补上第二次 Decode，明确验证“恰好一个值”。

什么时候不应该拒绝第二个 JSON 值？

当协议本身定义为连续 JSON 值流时，第二个值是合法数据，应循环解码直到 EOF。是否检查尾随内容不是 Decoder 的统一开关，而是由你的输入协议决定。

结论很简单：第一次 Decode 回答“能否读取下一个 JSON 值”，第二次调用回答“后面是否真的结束”。只有这两个条件同时成立，才能把输入当作恰好一个完整 JSON 值。