Go 怎样拒绝 JSON 中未声明字段

Go 的 encoding/json 默认会忽略 JSON 对象里没有对应结构体字段的键。如果请求体里多写了一个拼写错误的字段，解码仍可能成功，业务层接收到的却是一个缺少关键信息的结构体。需要把这类输入当作错误时，在调用 Decode 之前对 json.Decoder 调用 DisallowUnknownFields() 即可。

官方文档：https://pkg.go.dev/encoding/json

严格字段模式的核心不是“禁止 JSON 多出任何内容”，而是要求对象键能匹配目标结构体中未忽略的导出字段。它适合明确契约的请求边界；对需要向前兼容的事件消费，则要先评估升级策略。

默认解码为什么会放过拼写错误

假设接口只接受用户资料的 name 和 age，调用方却把 name 写成了 nmae。普通的 json.Unmarshal 或 Decoder.Decode 会把无法匹配的对象键跳过，不会因为这个键没有目标字段而自动报错。字段名写错、前端发送旧字段、客户端误加调试字段，都会落入这个默认行为。

这是一种兼容性取舍：新增字段的客户端可以把数据发给旧服务，旧服务只读取自己认识的字段。但在创建、更新、配置这类希望尽早发现契约错误的入口，静默忽略也会让问题延迟到业务校验甚至数据落库之后。

用 DisallowUnknownFields 把契约边界立在 Decode 前

DisallowUnknownFields 是 Decoder 的配置方法。它只需要在解码前调用一次，随后当目标是结构体且输入对象包含无法匹配、未被忽略的导出字段时，Decode 返回错误。这个设置作用于当前 Decoder，不会修改全局 JSON 行为。

package main

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

type Profile struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func decodeProfile(input string) error {
    var profile Profile
    dec := json.NewDecoder(strings.NewReader(input))
    // 在第一次 Decode 前开启严格字段匹配，避免拼写错误被静默忽略。
    dec.DisallowUnknownFields()
    if err := dec.Decode(&profile); err != nil {
        return fmt.Errorf("解码用户资料: %w", err)
    }
    fmt.Printf("资料=%+v\n", profile)
    return nil
}

func main() {
    // name 被误写成 nmae 时，严格 Decoder 会返回未知字段错误。
    if err := decodeProfile(`{"nmae":"小林","age":28}`); err != nil {
        fmt.Println("请求无效:", err)
    }
}

代码里的 nmae 没有对应的 json 标签或字段，因此应进入错误分支。注意这里用的是 Decoder 而不是直接调用 json.Unmarshal：严格未知字段策略属于 Decoder 的方法配置。

把严格解码放进 HTTP 请求边界

实际服务中，严格模式应靠近请求体入口。除了未知字段，还要明确请求体大小、关闭响应或请求资源，以及是否允许一个请求体后面继续粘连第二个 JSON 值。下面的示例把“只接受一个 JSON 对象”的意图写进函数，避免把一次成功的首个 Decode 误当成整个输入已经结束。

package api

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

type CreateProfile struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func decodeSingleProfile(r *http.Request) (CreateProfile, error) {
    var profile CreateProfile
    dec := json.NewDecoder(io.LimitReader(r.Body, 1

示例用 io.LimitReader 控制读取规模，但它是容量边界，不是严格字段检查的替代品。生产代码还可以在业务层检查年龄范围、名字是否为空等语义规则；DisallowUnknownFields 只负责对象键和目标结构体字段是否匹配。

第二次 Decode 的检查是一个额外的输入边界：如果接口只接受一个 JSON 文档，首个对象解码成功后，后面再出现第二个值也应拒绝。若接口本来就是 JSON 流，则不要照搬这个尾部规则，而应按流协议连续读取。

哪些字段会被视为已声明

严格模式不是简单比较 Go 字段名字符串。导出的结构体字段可以通过 json:"name" 指定输入键；带有 json:"-" 的字段被明确忽略；未导出的字段不能作为普通 JSON 输入目标。嵌套结构体的对象键也会在对应的嵌套目标上继续匹配。

type Request struct {
    UserID string `json:"user_id"`
    Meta   struct {
        TraceID string `json:"trace_id"`
    } `json:"meta"`
    // 这个字段明确不参与JSON输入，因此不会成为可接收的键。
    InternalNote string `json:"-"`
}

// 下面这些键可以匹配：user_id、meta、meta.trace_id。
// internal_note 即使出现在输入中，也不能借助被忽略字段接收。

实际项目里应把外部请求 DTO 与内部领域对象分开。这样严格模式只约束边界 DTO，不会因为内部结构为了计算、审计或缓存增加了字段，就意外改变公共 JSON 契约。遇到匿名嵌套字段、同名字段和标签冲突时，应按照实际字段设计消除歧义，而不是用放宽模式掩盖。

严格模式不是所有消息消费者的万能开关

对前端提交的创建、更新、配置接口，拒绝未知字段通常能更早暴露客户端拼写问题，也能防止调用方以为某字段已经被服务端处理。对事件总线、持久化消息或滚动发布中的跨版本协议，生产者往往会先增加字段；消费者如果必须兼容未来字段，就可能需要保留默认忽略行为，或者把未知字段收集到专门的扩展区。

如果想同时获得严格核心字段和可扩展数据，可以把扩展内容放入命名明确的字段，例如 extensions，让严格模式检查顶层结构、让扩展区承担可变键。不要通过关闭严格模式来实现一个没有边界的“万能 JSON”。

排查严格解码报错时先看这份清单

• 确认调用的是同一个已经设置过 DisallowUnknownFields 的 Decoder，而不是后面又换成 json.Unmarshal。
• 确认输入键与 json 标签一致，尤其是下划线、大小写和嵌套层级。
• 确认字段是导出的；小写字段不能作为普通目标字段接收 JSON。
• 确认被拒绝的键不是客户端误发的旧字段，并决定是修客户端还是做显式迁移。
• 如果服务接受 JSON 流，区分“拒绝未知字段”和“拒绝第二个 JSON 值”这两个不同策略。

错误日志应记录接口名、字段错误和请求追踪标识，不要直接打印可能含有隐私数据的完整请求体。严格模式解决的是字段契约，不会自动完成鉴权、权限、业务范围或敏感数据审计。

常见问题

能不能让 json.Unmarshal 也拒绝未知字段？

标准做法是改用 json.NewDecoder，在 Decode 前配置 DisallowUnknownFields。不要期待给 Unmarshal 传一个开关参数。

未知字段被拒绝后，缺失字段也会自动报错吗？

不会。严格模式关注输入里多出的对象键；必填字段是否存在、值是否满足业务规则，需要由结构体校验或业务代码另行判断。

只要结构体里有同名字段就一定能接收吗？

还要看字段是否导出、是否被 json:"-" 忽略以及标签是否改变了键名。把目标结构体设计成边界 DTO，通常比直接复用内部对象更容易判断。

把严格字段策略放在哪里，取决于协议是否允许向前兼容；但一旦选择严格模式，就应让它靠近输入边界，并把请求体关闭、单文档尾部和业务校验这些相邻责任分开。这样“未知字段”会在最接近来源的位置失败，后续代码看到的结构体才更可信。