Go JSON Decoder 为什么读到 EOF：连续 JSON、空白与尾部脏数据怎么判

处理 HTTP 请求体或者消息队列里的 JSON 数据时，json.Decoder.Decode 返回 io.EOF 不一定是异常报错。连续 JSON 流全部读完的场景下，EOF 属于正常结束状态；如果是 JSON 在传输中途被截断，通常会先返回语法错误；要是只做了一次解码，第一个对象解析成功就直接返回，反而很容易放过尾部的脏数据。

先把 EOF 放回 JSON 读取现场

下面这段代码会读取两个紧挨着写的 JSON 对象。第一次 Decode 能正常读出订单对象，第二次读出用户对象；第三次再调用读才会返回 EOF。EOF 出现在流的最末尾，完全不代表前面两个 JSON 对象有解析问题。

var in = strings.NewReader(`{"id":101}{"id":102}`)
dec := json.NewDecoder(in)

for {
    var item struct {
        ID int `json:"id"`
    }
    err := dec.Decode(&item)
    if errors.Is(err, io.EOF) {
        break
    }
    if err != nil {
        return fmt.Errorf("decode item: %w", err)
    }
    fmt.Println(item.ID)
}

这里的判断顺序非常关键：先单独判断 EOF，再处理其余错误。不要把所有非 nil 的错误都统一打印成“JSON 格式错误”，不然会把消息流正常结束和输入本身损坏这两类完全不同的场景混为一谈。

单对象接口为什么要再 Decode 一次

很多对外接口的约定里，请求体只能携带一个 JSON 值。这时候你只调用一次 Decode 是不够的，因为输入 {"name":"go"}{"name":"extra"} 的第一次解码也能正常返回成功。安全的标准做法是：解出主业务对象之后，再额外解码一次，只有拿到 EOF 结果的时候，才能说明后面没有藏着第二个额外的 JSON 值。

func decodeOne(r io.Reader, dst any) error {
    dec := json.NewDecoder(r)
    if err := dec.Decode(dst); err != nil {
        return fmt.Errorf("read body: %w", err)
    }

    var extra any
    err := dec.Decode(&extra)
    if errors.Is(err, io.EOF) {
        return nil
    }
    if err == nil {
        return errors.New("request body contains more than one JSON value")
    }
    return fmt.Errorf("check trailing JSON: %w", err)
}

第二次解码遇到空白字符之后返回 EOF，属于完全符合预期的结果；如果额外读出了第二个业务值，说明调用方多发了内容；如果尾部是半截不完整的 JSON，就应该直接按非法请求处理。这个几行代码的小检查，能挡住代理内容拼接、客户端参数误写、请求体复用带来的很多非常隐蔽的线上问题。

输入被截断时，错误通常长什么样

把 {"name":"go" 这样的半截不完整内容交给 Decoder 处理，第一次解码不会返回 EOF，反而会直接返回语法错误。EOF 只代表底层读取器已经没有更多字节可以读；如果当前正在解析的值还没闭合，解析器明确知道输入内容不完整，就会把出错位置和当前语法状态一并带出来。

var dst map[string]string
err := json.NewDecoder(strings.NewReader(`{"name":"go"`)).Decode(&dst)
if err != nil {
    var synErr *json.SyntaxError
    if errors.As(err, &synErr) {
        fmt.Println("bad JSON at byte", synErr.Offset)
    }
}

记录具体的错误类型，比只打印一句“decode failed”好用得多。服务端可以把 JSON 语法错误直接映射为 400 状态码，把读取超时或者连接中断的错误单独做指标统计；消息消费者则可以根据自身的消息协议规则，决定是直接丢弃、重试还是把这条消息转入死信队列。

连续 JSON 和 JSON 数组不要混用读取策略

连续 JSON 流适合边读边处理，不需要等整个输入全部加载完拼成完整数组；标准 JSON 数组则要先读取数组开始标记，再逐个读取内部元素，最后还要确认数组本身已经正常闭合。两种场景都能用标准库的 Decoder 实现，但结束判断的逻辑完全不一样，不能直接把“循环读到 EOF 就退出”的逻辑套到数组内部的读取流程里。

• 单个对象场景：Decode 主值之后，再额外 Decode 一次确认拿到 EOF。
• 连续多对象流场景：循环调用 Decode，遇到 EOF 就结束循环；中途碰到其他非 nil 错误立刻停止处理。
• 标准数组场景：检查数组边界标记，内部每个元素解码成功不等于整个数组已经完整闭合。

常见问题：Decode、EOF 与尾部数据

第二次 Decode 返回 EOF 需要记录成错误吗？

对“请求体只能有一个 JSON 值”的接口来说，这个结果是成功信号，代表尾部只有空白字符。对连续流处理场景来说，它也是整个流的自然结束信号。是不是错误，完全由你当前业务的输入协议定义。

用 json.Unmarshal 能自动拒绝第二个 JSON 值吗？

Unmarshal 适合已经拿到完整字节的单个 JSON 值场景；如果你直接把整个请求体全部读到内存再解析，还要提前做好读取大小上限的控制。流式场景下直接用 Decoder，显式检查尾部剩余内容的逻辑会更清晰直接。

如何避免恶意请求把 Decoder 卡在大输入上？

在 HTTP 层先给请求体设置好大小上限和读取超时，业务层再补充字段范围和嵌套深度的约束。解析成功只说明内容符合 JSON 语法，完全不代表内容符合你的业务校验规则。

最后的判断

判断 json.Decoder 的错误之前，先理清楚当前输入协议约定是单值、连续流还是标准数组，再定义 EOF 对应的含义。单值接口要补上一次尾部校验，连续流要把 EOF 当成正常结束信号，截断和脏数据则按各自对应的错误类型单独处理。这样写出来的代码虽然多了几行，却能真正把“解析正常结束”和“请求内容损坏”这两类之前容易混的场景彻底分开。