Go json.Decoder 怎样拒绝请求体尾部脏数据

在 HTTP 接口里，下面这种写法很常见：创建 json.Decoder，调用一次 Decode，成功后就认为请求体合法。但 Decoder 的设计目标是读取连续的 JSON 值，一次 Decode 只消费下一个值，不负责替你确认输入流已经结束。请求体如果是 {"name":"Ada"}{"name":"Bob"}，第一次解码仍然可能成功。

严格只接受一个 JSON 值时，首次 Decode 后必须再调用一次 Decode，并且只把 io.EOF 当作“没有尾部数据”。 第二次返回 nil，说明后面还有第二个合法 JSON 值；返回其他错误，说明尾部存在非法字符或不符合目标类型的数据，这两种情况都应拒绝。

先分清“值结束”和“输入结束”

json.NewDecoder 读取的是一个流。官方文档把 Decoder 描述为可以从输入流读取 JSON values，示例也会循环调用 Decode 直到 io.EOF。因此，下面两件事不能混为一谈：第一，当前结构体已经被一个 JSON 对象填充；第二，Reader 中已经没有下一个 JSON 值。

这也是尾部脏数据容易漏掉的原因。{"name":"Ada"} trailing 的第一个对象是完整的，第一次调用可能已经把它交给业务层；尾部是否存在内容，要靠下一次读取才能确认。空白字符属于 JSON 值之间允许的分隔内容，第二次调用遇到它们后仍应返回 io.EOF。

用第二次 Decode 严格拒绝尾部内容

先写一个只接受单个 JSON 值的通用函数。第一次调用负责业务对象，第二次调用不关心尾部具体是什么，只把它放进 any。这样第二个合法对象、数组、字符串或数字都会返回 nil，统一进入“存在多个 JSON 值”的拒绝分支。

package main

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

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

// decodeOneJSON 只允许 reader 中出现一个完整 JSON 值。
func decodeOneJSON(reader io.Reader, dst any) error {
	dec := json.NewDecoder(reader)
	if err := dec.Decode(dst); err != nil {
		// 首次 Decode 返回 EOF，表示请求体为空，不能当成成功请求。
		if errors.Is(err, io.EOF) {
			return errors.New("请求体不能为空")
		}
		return fmt.Errorf("首个 JSON 值无效: %w", err)
	}

	var extra any
	if err := dec.Decode(&extra); err != io.EOF {
		if err == nil {
			// 第二次成功说明请求体中还有另一个合法 JSON 值。
			return errors.New("请求体只能包含一个 JSON 值")
		}
		// 非 EOF 错误通常表示尾部有非法字符或不完整值，也要拒绝。
		return fmt.Errorf("请求体尾部不是空白: %w", err)
	}
	return nil
}

func main() {
	var user CreateUser
	err := decodeOneJSON(strings.NewReader(`{"name":"Ada"}   `), &user)
	fmt.Printf("user=%+v err=%v\n", user, err)
}

这里的关键判断是 err != io.EOF，而不是只判断第二次是否成功。尾部再放一个合法 JSON 值时，第二次返回 nil；尾部是 oops 时，第二次返回语法错误；尾部是一个无法解码到临时目标的值时，也会得到类型错误。它们虽然错误类型不同，但业务结论相同：输入不是“一个 JSON 值加可忽略空白”。

把检查接到 HTTP 请求体

在 Handler 中，可以把未知字段检查和尾部检查放在同一个 Decoder 上。DisallowUnknownFields 只约束 JSON 对象的键是否能映射到导出字段，它不会检查对象后面是否还跟着第二个值，所以仍然要保留第二次 Decode。

func createUserHandler(w http.ResponseWriter, r *http.Request) {
	defer r.Body.Close() // Handler 结束时释放请求体资源。

	var input CreateUser
	dec := json.NewDecoder(r.Body)
	dec.DisallowUnknownFields() // 未知字段单独按请求错误处理。

	if err := dec.Decode(&input); err != nil {
		// 空请求体和 JSON 语法错误都不能进入业务层。
		http.Error(w, "请求体 JSON 无效", http.StatusBadRequest)
		return
	}

	var extra any
	if err := dec.Decode(&extra); err != io.EOF {
		// nil 代表第二个合法值，其他错误代表尾部脏字节。
		http.Error(w, "请求体只能包含一个 JSON 值", http.StatusBadRequest)
		return
	}

	w.WriteHeader(http.StatusCreated) // 只有完整消费单值请求体才创建资源。
}

示例中的响应文案可以按项目错误协议调整，但判断顺序不要省略：先确认首个值能解码，再确认没有第二个值。生产接口还应在进入 JSON 解码前设置合理的请求体大小上限，例如用 http.MaxBytesReader 包住 r.Body；大小限制解决资源消耗问题，尾部探测解决消息边界问题，两者不能互相替代。

多 JSON 流和严格单值接口不要混用

第二次 Decode 的规则适合一个请求对应一个 JSON 文档的 REST 接口。如果协议本来就是连续 JSON 流，例如每行一个 JSON 对象，或者一个连接里约定连续传输多个值，就不应该把第二个值直接判为错误，而应在循环中持续 Decode，并明确记录每条消息的边界和错误策略。

常见问题

为什么第一次 Decode 成功还不能返回 200？

因为 Decoder 面向输入流，第一次调用只消费下一个 JSON 值。请求体后面可能还有第二个合法值或非法字符，必须再次 Decode 才能确认边界。

只检查 dec.Buffered() 是否为空可以吗？

不建议。Buffered 返回的是 Decoder 已读入但尚未消费的缓冲区，而且缓冲区只代表当前实现已经预读的部分，不能代替继续按 JSON 语法探测整个输入。

DisallowUnknownFields 能防止尾部数据吗？

不能。它只拒绝对象中无法映射的字段名；对象之后的第二个值属于输入流边界问题，要用第二次 Decode 单独判断。

把“首个值可解码”和“输入已经结束”拆成两个检查，接口就不会因为一次成功的 Decode 而误收半截或拼接请求。单值 JSON 请求体使用 io.EOF 作为结束信号，多值协议则明确采用循环读取，边界自然会清晰很多。