Go 接口收到多余 JSON 字段为什么没有报错

这个现象通常不是接口没有收到字段，而是 Go 标准库的默认行为：把 JSON 解码到结构体时，输入对象里找不到对应结构体字段的键会被忽略，不会自动返回错误。要把“客户端多传字段”变成可见错误，应使用 json.Decoder，在 Decode 前调用 DisallowUnknownFields()。如果接口还要兼容旧客户端，则先记录未知字段，再按接口版本逐步收紧。

为什么默认解码会放过多余字段

假设请求体是 {"name":"Lin","email":"lin@example.com","debug":true}，而目标类型只有 Name 和 Email。字段名或 json 标签能够匹配的值会写入结构体；debug 没有对应的可用字段，就被静默跳过。JSON 语法正确、类型也正确，所以这不是解码错误。

这也是很多接口“拼写错了却返回成功”的根因。比如客户端把 display_name 写成 dispay_name，服务端得到的只是空字符串。默认宽松策略适合需要向后兼容的输入，但不适合把请求体当作严格契约的创建、更新接口。

用 Decoder.DisallowUnknownFields 开启严格校验

严格模式的关键是把输入交给 Decoder，而不是继续使用 json.Unmarshal。官方文档说明：当目标是结构体，且输入对象键无法匹配非忽略的导出字段时，DisallowUnknownFields 会让 Decoder 返回错误。

package main

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

type UserInput struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func main() {
    body := `{"name":"Lin","email":"lin@example.com","debug":true}`
    var input UserInput
    dec := json.NewDecoder(strings.NewReader(body))
    dec.DisallowUnknownFields() // 把未声明的对象键视为解码错误
    if err := dec.Decode(&input); err != nil {
        fmt.Println("请求字段无效:", err)
        return
    }
    fmt.Printf("%+v\n", input)
}

运行时错误会指出类似 json: unknown field "debug"。注意这个方法不是“所有 JSON 都严格”：目标如果是 map[string]any，键本来就是动态数据；目标如果含有被 json:"-" 忽略的字段，也不能靠它恢复该字段。严格校验应放在请求契约明确的结构体入口。

怎么把严格校验接到 HTTP Handler

线上 Handler 不建议只加一行严格开关就结束。解码成功后再尝试一次 Decode，可以拒绝同一个请求体中偷偷拼接的第二个 JSON 值；空体、非法类型和未知字段则统一转成客户端可理解的 400。

func decodeUser(w http.ResponseWriter, r *http.Request) (UserInput, error) {
    var input UserInput
    dec := json.NewDecoder(r.Body)
    dec.DisallowUnknownFields() // 先拒绝结构体没有声明的字段
    if err := dec.Decode(&input); err != nil {
        return UserInput{}, fmt.Errorf("读取请求体: %w", err)
    }

    var extra any
    if err := dec.Decode(&extra); err != io.EOF {
        // 第二个 JSON 值或尾随非空内容都不属于一个请求
        if err == nil {
            return UserInput{}, errors.New("请求体包含多个 JSON 值")
        }
        return UserInput{}, fmt.Errorf("请求体尾部无效: %w", err)
    }
    return input, nil
}

func userHandler(w http.ResponseWriter, r *http.Request) {
    input, err := decodeUser(w, r)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest) // 统一返回 400
        return
    }
    _ = input // 这里交给业务服务继续处理
    w.WriteHeader(http.StatusNoContent)
}

示例省略了业务字段校验，但保留了请求体资源的关闭工作应由框架或上层负责的约定。生产代码还可以限制 Content-Length 或用 http.MaxBytesReader 控制体积；这些是大小边界，不等同于未知字段校验。

按接口兼容性选择灰度与排障策略

严格模式会改变旧客户端的结果：以前多传字段还能成功，现在会收到 400。因此新接口、内部服务和字段契约要求明确的写入接口可以直接开启；已有公共接口应先观察一段时间，记录未知字段名和调用方，再安排客户端升级。

• 先确认入口：检查实际调用的是不是这段 Decoder；若仍走 json.Unmarshal，开关不会生效。
• 再确认目标：只有解码到结构体时才有“未知字段”这个边界，动态 map 不适用。
• 最后确认请求：区分拼写错误、版本字段、代理追加字段和真正恶意输入，不能只看 400 数量。

推荐把错误日志记录为接口名、字段名和客户端版本，避免记录完整请求体中的隐私数据。等未知字段来源稳定后，再让新版本接口启用 DisallowUnknownFields；回滚时只回退严格策略，不要把错误字段悄悄写入业务模型。

常见问题

json.Unmarshal 能不能直接配置严格模式？

不能直接调用同名配置。需要创建 json.Decoder，调用 DisallowUnknownFields 后再 Decode。

json 标签写错会被当成未知字段吗？

如果输入键匹配不到任何可用字段，就会被默认忽略；严格模式下会报未知字段错误。先检查标签拼写和大小写。

开启严格模式后为什么仍可能放过数据？

目标若是 map、字段被显式忽略，或未知字段藏在自定义 UnmarshalJSON 自己处理的对象里，行为就不再等同于普通结构体解码。要从实际解码入口继续排查。