Go json.Decoder 如何检测 JSON 流中间的截断记录

处理日志上传、批量接口或消息消费时，输入常常不是一个 JSON 文档，而是连续排列的多个 JSON 值。判断是否截断的关键不是看字符串末尾有没有换行，而是看 Decode 在读取下一条记录前后返回了什么错误：尚未开始下一条值就遇到 io.EOF，通常表示流正常结束；已经读进半个对象、数组或字符串后才到输入末尾，则应按失败记录处理。

循环读取连续 JSON 时，只把“下一条记录尚未开始”的 io.EOF 当作正常结束；对当前记录中途结束的输入，保留错误、偏移和原始分片，等待重试或进入坏数据队列。

先把连续 JSON、截断输入和文件结尾分开

NewDecoder 接收一个 io.Reader，可以连续解码类似 {"id":1} {"id":2} 的值。它会跳过值之间的空白，并且可能从 Reader 预读超过当前请求的 JSON 值。因此，循环的退出条件必须围绕错误语义，而不是围绕换行符。

第一条记录完整解码后，下一次调用如果没有任何非空白字节，返回 io.EOF，这是干净结束。相反，输入为 {"id":1}{"id": 时，第二次解码已经开始读取对象，末尾缺少值，不能把它当成“没有下一条”。生产代码应保留当前序号、来源分片和错误，再决定等待更多字节还是隔离记录。

用 Decode 循环逐条读取，并只分类真正的结束

下面的示例把每条记录放入独立变量，避免上一条成功数据残留在本次失败结果里。示例也把空输入、正常结束和截断输入分开记录：

package main

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

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

func readEvents(input string) error {
	dec := json.NewDecoder(strings.NewReader(input))
	for index := 1; ; index++ {
		var event Event // 每次循环都用新值，失败时不会复用上一条记录。
		err := dec.Decode(&event)
		if errors.Is(err, io.EOF) {
			return nil // 没有开始下一条 JSON 值，才是正常结束。
		}
		if err != nil {
			var syntaxErr *json.SyntaxError
			if errors.As(err, &syntaxErr) {
				return fmt.Errorf("第 %d 条记录在字节 %d 附近损坏: %w", index, syntaxErr.Offset, err)
			}
			if errors.Is(err, io.ErrUnexpectedEOF) {
				return fmt.Errorf("第 %d 条记录被截断，当前偏移 %d: %w", index, dec.InputOffset(), err)
			}
			return fmt.Errorf("第 %d 条记录解码失败，当前偏移 %d: %w", index, dec.InputOffset(), err)
		}
		fmt.Printf("accepted id=%d state=%s\\n", event.ID, event.State) // 只有 Decode 成功才提交业务处理。
	}
}

这里的顺序很重要：先用 errors.Is 判断结束和意外 EOF，再用 errors.As 取出语法错误。不同 Go 版本或不同输入形态下，截断可能表现为语法错误文本或意外 EOF；业务层不应只匹配错误字符串。

用 InputOffset 定位失败记录，并决定是否重试

InputOffset 返回当前解码器位置的字节偏移，适合写进日志、指标标签之外的结构化字段，便于从原始文件或消息分片中定位。它不是字符数，也不是行号；如果输入含有中文，按字节计算更容易和原始存储对齐。

日志最好同时保存记录序号、来源消息 ID、InputOffset()、错误类型和重试次数。不要把偏移直接当作可以安全切片的位置：Decoder 可能已经预读数据，而且 UTF-8 字符不能按一个字节简单截开。

处理 Decoder 缓冲，避免恢复时丢掉预读字节

官方文档明确说明，Decoder 自带缓冲，Buffered 可以读取上一次 Decode 或 Token 之后内部尚未消费的数据，但这个 Reader 只保证在下一次 Decode 或 Token 前有效。需要把剩余数据和底层 Reader 的后续内容拼接时，应在下一次解码前完成复制或封装。

如果协议允许一条记录跨多个网络分片，最稳妥的做法是让上层把分片组装成可重放的输入，再交给 Decoder；不要在 Decoder 已经读入半条记录时，凭 InputOffset 直接从底层连接重新读取。文件导入则可以记录原始文件偏移和记录编号，重试时从可确认的分片边界重新开始。

常见问题

连续 JSON 值之间必须换行吗？

不必须。JSON 空白可以是空格、换行或制表符，Decoder 会按语法识别下一个值。真正重要的是值本身完整且彼此可区分。

看到 unexpected EOF 就一定是网络断开吗？

不一定。它只说明输入在当前 JSON 值完成前结束，原因可能是网络分片、文件被截短或上游生成了不完整内容，还需要结合来源状态判断。

为什么不直接用 json.Valid 检查整个流？

json.Valid 更适合检查一段完整 JSON 数据。连续值和流式输入需要逐条处理，Decode 循环才能知道哪一条成功、哪一条在什么偏移失败。

把“正常结束”和“记录内部截断”分开后，JSON 流处理就有了明确的提交边界：Decode 成功才处理业务，EOF 只负责收尾，其他错误都带着记录上下文进入恢复或隔离流程。