Go json.Decoder 与 json.Unmarshal 怎么选：连续 JSON 请求的边界问题

线上有个批量导入接口出了个反常的现象：客户端发来的请求体明明是两个连在一起的JSON，服务端第一次解析拿到预期结构体就直接返回成功，后续多出来的第二段JSON完全没触发报错就被悄悄跳过了。排查后发现，json.Decoder 不是“只解析一个对象的工具”，它对接的是可持续读取的流；如果接口约定只允许传一个 JSON，就必须主动检查后面是否还有剩余内容。

两个API的选择核心看你的输入边界约定，单JSON请求优先用带全量剩余校验的解析逻辑，不要默认API会帮你做完整段输入的合法性校验。

问题出在“一个请求只能有一个 JSON”这条边界

很多Go接口从 r.Body 拿数据时，第一反应是从两种常用写法里挑一个。它们都能把JSON映射成业务结构体，但对输入边界的校验逻辑完全不一样。

type CreateOrder struct {
    UserID int64  `json:"user_id"`
    Amount int64  `json:"amount"`
}

// 写法一：一次读完再解析
raw, err := io.ReadAll(r.Body)
if err != nil {
    return err
}
var req CreateOrder
if err := json.Unmarshal(raw, &req); err != nil {
    return err
}

// 写法二：直接从请求流解析
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
    return err
}

如果请求体是 {"user_id":7,"amount":99}，两种方式跑起来结果看起来完全一致。差异都藏在异常场景里：{...}{...}、合法 JSON 后面额外夹了一段文本、或者请求体大到不该直接全读进内存。接口的契约不一样，选择的解析方式也该跟着变。

json.Decoder 为什么会读到下一个 JSON

Decoder 绑定了一个 io.Reader，每次调用 Decode 都会从当前读取位置往后找下一个合法的 JSON 值。因此下面的测试会成功两次：

body := strings.NewReader(`{"user_id":7}{"user_id":8}`)
dec := json.NewDecoder(body)

var first, second CreateOrder
err1 := dec.Decode(&first)
err2 := dec.Decode(&second)

fmt.Println(err1, first.UserID)  //  7
fmt.Println(err2, second.UserID) //  8

这不是解析器出错，而是流式接口的正常行为。真正容易踩坑的是：接口本来只允许一个对象，却只调用一次 Decode 就返回成功。攻击者或配置错误的客户端可以把第二个 JSON、额外字段甚至无关文本附在后面，而业务代码完全感知不到。

单对象接口怎样确认后面没有第二段内容

第一次解码成功后，再调用一次 Decode，预期结果必须是 io.EOF。为了允许尾部空白，直接让解码器处理空格即可：

dec := json.NewDecoder(r.Body)
if err := dec.Decode(&req); err != nil {
    return fmt.Errorf("读取请求 JSON 失败: %w", err)
}

var extra any
if err := dec.Decode(&extra); err != io.EOF {
    if err == nil {
        return errors.New("请求体包含多个 JSON 对象")
    }
    return fmt.Errorf("请求体尾部不是合法空白: %w", err)
}

生产接口还应限制请求体大小。下面的限制放在解析前，避免大请求先被完整读入：

r.Body = http.MaxBytesReader(w, r.Body, 1

json.Unmarshal 和 json.Decoder 的选择边界

我通常不把这两个API当成“谁更先进”的替代关系，而是先看数据存放在哪里、是否需要一次性校验整段输入，以及输入体积会不会很大。下面这张对照表比死记语法更实用。

别把 Decoder 当成天然的流式低内存保证

Decoder 不等于“内存一定很小”。如果目标结构里有很长的字符串、巨大数组，解析结果本身仍然需要占用内存；解码器只是不要求你先把整个请求体复制成一个 []byte。所以入口大小限制、字段数量限制和业务层数量限制仍然要做。

需要严格拒绝未知字段时，记得开启 DisallowUnknownFields

默认情况下，JSON 里的未知键会被忽略。客户端把 amout 拼错时，服务端可能收到一个金额为零的结构体，问题直到业务校验环节才会暴露出来。对内部接口或变更敏感的请求，可以启用 DisallowUnknownFields，再配合明确的参数校验规则。

一段可复用的单 JSON 请求解析函数

把边界检查逻辑集中起来，handler 里会少很多重复判断。这个函数只接受一个 JSON 值、拒绝未知字段，并把超大请求转换成可识别的错误。

var ErrBodyTooLarge = errors.New("request body too large")

func decodeOneJSON(w http.ResponseWriter, r *http.Request, dst any) error {
    r.Body = http.MaxBytesReader(w, r.Body, 1

这里的第二次解码是关键检查点。若接口将来改成 NDJSON，就不要复用这个函数，而应明确写循环，并记录每条记录的行号和错误原因。

常见问题：解析成功不代表请求就是合法的

json.Unmarshal 会接受两个连续 JSON 吗？

不会。它要求输入整体对应一个 JSON 值，后面还有非空白内容时会返回语法错误；但它同样不会替你完成字段语义校验。

什么时候应该用 Decoder.Decode 循环？

当协议明确规定请求体是多个 JSON 值，例如 NDJSON 日志或批量流时才使用。循环中要设置条数上限，并区分正常 EOF 与中途格式错误。

只设置 http.Client.Timeout 能解决服务端请求体问题吗？

不能。它控制客户端整体请求时间，服务端仍应限制请求体大小、校验输入边界，并在业务层验证字段和数量。

把选择写成团队约定

单个 JSON 请求默认使用带大小限制的 Decoder，并在第一次解码后检查 io.EOF；已有 []byte 且需要整体解析时使用 Unmarshal；只有协议明确允许多个值时才写解码循环。把这三条写进接口评审清单，后续看到“解析成功”时，就不会误以为请求边界也已经验证过。