JSON 流结束

用 encoding/json.Decoder 读取一段连续 JSON 时，最后一次 Decode 返回 io.EOF，通常就是“流里没有下一个 JSON 值了”。它不是解析失败，也不是应该继续重试的信号。

真正需要保留的判断只有一条：先单独处理 io.EOF，再把其他错误原样返回。这样既能正常结束单值流，也不会把半截 JSON 或非法 JSON 静默吞掉。

核心结论：对独立 JSON 值组成的流，err == io.EOF 表示正常结束；io.ErrUnexpectedEOF、*json.SyntaxError 或目标类型错误都仍然是失败。

Decode 循环的接口目标：读完才是 io.EOF

Decoder 面向的是 io.Reader，它可以连续读取多个相互独立的 JSON 值，例如两个对象之间只用空白分隔。每次成功调用得到一个值；当输入已经耗尽，再调用一次才会返回 io.EOF。

官方示例也是这个判断顺序：遇到 io.EOF 跳出循环，其他错误进入失败分支，成功解码的值才交给业务处理。

调用方如何区分正常结束和真实错误

最稳妥的写法是把 EOF 放在错误判断的第一层。下面的例子把两个独立对象放在同一条流中，空白只负责分隔，不需要手动按换行切分。

package main

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

type Event struct {
	Name string `json:"name"`
}

func main() {
	// 两个 JSON 值组成一条流，Decoder 会按值读取而不是按行读取。
	dec := json.NewDecoder(strings.NewReader(`{"name":"start"} {"name":"finish"}`))
	for {
		var event Event
		if err := dec.Decode(&event); err != nil {
			if err == io.EOF {
				// 没有下一个完整值，表示流正常结束。
				break
			}
			// 截断、语法错误或类型错误不能当成正常结束。
			panic(err)
		}
		fmt.Println(event.Name)
	}
}

如果项目里会包装错误，也可以用 errors.Is(err, io.EOF)。关键不在比较形式，而在于只把 EOF 当作结束；不要用“所有非 nil 错误都结束”这种写法。

错误模型：EOF、截断和语法错误不是一回事

空输入或只剩空白时，Decoder 找不到下一个值，会给出 io.EOF。如果输入已经开始了一个 JSON 值，却在值完成前结束，例如只有 {"name"，则属于输入被截断，通常会得到 io.ErrUnexpectedEOF，不能跳过。

同样，JSON 语法不成立时会返回语法错误；JSON 结构合法但无法放入目标 Go 类型时，也会返回类型错误。它们都说明“流中存在一个需要处理的问题”，不是“流自然结束”。

数组内部不要用 EOF 判断元素结束

上面的循环适合读取独立 JSON 值流。如果输入是一个完整数组，例如 [{"name":"start"},{"name":"finish"}]，数组元素的结束由右方括号决定，应该让 More 判断当前容器是否还有元素。

package main

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

type Event struct {
	Name string `json:"name"`
}

func main() {
	// 数组边界由 Token 读取，More 只判断当前数组内是否还有值。
	dec := json.NewDecoder(strings.NewReader(`[{"name":"start"},{"name":"finish"}]`))
	_, _ = dec.Token() // 读取数组开始符号 [。
	for dec.More() {
		var event Event
		if err := dec.Decode(&event); err != nil {
			panic(err)
		}
		fmt.Println(event.Name)
	}
	_, _ = dec.Token() // 读取数组结束符号 ]。
}

也就是说，独立值流用 Decode + io.EOF 表达“没有下一个值”；数组内部用 More 表达“当前容器没有下一个元素”。两个边界不要混用。

常见疑问

为什么 Decode 最后一次不是返回 nil？因为最后一次成功调用已经返回了最后一个值；下一次调用才是在询问“还有没有值”，此时 EOF 才有意义。

收到 io.ErrUnexpectedEOF 能当作流结束吗？不能。它表示一个 JSON 值已经开始但没有完整结束，通常需要让上层报错、重传或等待更多数据。

读取 HTTP 响应时也一样吗？如果响应体承载的是独立 JSON 值流，Decode 的 EOF 语义一样；但响应体本身仍要按 HTTP 客户端约定关闭，不能因为 EOF 就省略资源清理。

记住这张小表即可：