Go JSON 解码未知字段怎样避免静默忽略

接口收到 JSON 后，结构体里没有声明的字段默认不会报错，encoding/json 会把能匹配的字段填进去，其余字段直接跳过。这样做兼容性好，却也容易把客户端把 usernmae 写成 username 这类问题藏起来。

如果这个接口希望把字段拼写错误尽早暴露，可以改用 json.Decoder，在第一次 Decode 前调用 DisallowUnknownFields。官方文档说明，它会在目标是结构体、输入又包含未匹配的非忽略导出字段时返回错误。

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

默认写法为什么会静默忽略

最小的默认写法通常是 json.Unmarshal。它适合字段会逐步增加、客户端版本不完全同步的场景，但未知字段不会进入错误分支，调用方也就无法知道自己传了一个服务端不认识的键。

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

var req CreateUser
if err := json.Unmarshal(body, &req); err != nil {
	// 这里只能捕获 JSON 语法或类型等解码错误。
	return err
}
// body 中的 "nmae" 会被忽略，req.Name 仍保持空字符串。

因此，接口是否应该严格拒绝未知字段，不是 JSON 语法问题，而是输入契约的选择。面向固定客户端的命令接口通常更适合严格模式；需要向前兼容的公共接口则要谨慎切换。

用 DisallowUnknownFields 把多余字段变成错误

严格解码的关键是把输入交给 json.NewDecoder，先开启 DisallowUnknownFields，再调用 Decode。这个方法只改变当前 Decoder 的解码策略，不会改变结构体字段标签，也不需要为每个字段手写判断。

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

func decodeCreateUser(body io.Reader) (CreateUser, error) {
	var req CreateUser
	dec := json.NewDecoder(body)
	// 先收紧输入契约，再把未知字段交给统一错误处理。
	dec.DisallowUnknownFields()
	if err := dec.Decode(&req); err != nil {
		// 未知字段、语法错误和类型错误都会从 Decode 返回。
		return CreateUser{}, err
	}
	return req, nil
}

当请求是 {"name":"Lin","nmae":"Lin"} 时，Decode 会返回包含未知字段名称的错误，调用方可以将它转成 400 响应，而不是继续使用一个看似合法但字段不完整的对象。

错误处理要放在 Decode 的边界上

DisallowUnknownFields 负责发现问题，HTTP handler 负责决定如何呈现问题。不要用字符串匹配把所有解码错误都当成未知字段；语法错误、数字类型不匹配和未知字段的修复方向不同，统一返回客户端可理解的“请求体无效”通常更稳妥。

func createUser(w http.ResponseWriter, r *http.Request) {
	var req CreateUser
	dec := json.NewDecoder(r.Body)
	// 严格模式只作用于本次请求的 Decoder。
	dec.DisallowUnknownFields()
	if err := dec.Decode(&req); err != nil {
		// 记录服务端日志，客户端只收到稳定的错误类别。
		http.Error(w, "请求体字段或格式无效", http.StatusBadRequest)
		return
	}
	// 只有 Decode 成功后才进入业务层。
	w.WriteHeader(http.StatusCreated)
}

嵌套结构、标签和兼容期要看清

严格模式针对目标结构体的字段匹配。嵌套结构体在同一次解码中也会受到该 Decoder 的规则影响；字段是否匹配仍由导出字段和 json 标签决定。字段名写错、标签名改动或把 JSON 对象映射到不合适的 Go 类型，都可能让原本能接收的请求进入错误分支。

存量接口不要只因为“想更严格”就直接切换。可以先在日志中统计未知字段，再为新版本接口启用严格 Decoder；如果必须兼容旧客户端，也可以在明确的迁移窗口内保留旧入口，把严格模式放在新入口或新请求版本上。

采用建议：把输入契约说清楚

如果接口不接受未声明字段，使用 NewDecoder、DisallowUnknownFields、Decode 的组合即可。把错误处理留在解码边界，业务层只接收成功映射后的结构体；同时通过接口版本或迁移窗口处理旧客户端，避免把兼容策略混进结构体字段判断。

相关问题

• DisallowUnknownFields 会检查 JSON 数组吗？它主要约束数组元素被解码成结构体时的对象字段；数组本身是否为空、长度是否符合业务规则，仍应由业务层判断。
• json.Unmarshal 能直接开启严格模式吗？常见做法是改用 Decoder，因为 DisallowUnknownFields 是 Decoder 的方法。
• 未知字段错误要不要原样返回？开发环境可以保留字段名帮助定位，生产接口更适合返回稳定错误类别，同时把细节写入受控日志。