Go json.Decoder 开启 DisallowUnknownFields 后兼容旧客户端怎么办

开启 json.Decoder.DisallowUnknownFields 后，旧客户端多带或少带字段的兼容问题，不能靠“再加一个开关”解决：同一个 Decoder 只有严格或宽松两种策略。更稳妥的做法是把严格校验绑定到接口版本，让新客户端走严格入口，旧客户端走有记录、有期限的兼容入口。

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

先判断：这是未知字段，还是请求本身有错

官方定义很明确：目标是结构体时，输入对象里的键如果找不到对应的非忽略导出字段，开启该方法后 Decoder 返回错误。默认的 json.Unmarshal 则会忽略未知键。因此，旧客户端发来 trace_id、legacy_name 等历史字段时，严格接口会失败；这和字段类型错误、JSON 少了右括号不是一回事。

把严格校验放在新版本入口

不要让服务端根据“是否出现未知字段”来决定是否放宽，因为这样会让输入决定校验强度。可以把 /api/v1/orders 固定为兼容模式，把 /api/v2/orders 固定为严格模式；两条路径共享 DTO 和业务校验，只改变解码策略。

type OrderRequest struct {
	Name  string `json:"name"`
	Count int    `json:"count"`
}

func decodeOrder(r io.Reader, strict bool) (OrderRequest, error) {
	var req OrderRequest
	dec := json.NewDecoder(r)
	if strict {
		// 新版本拒绝 DTO 中没有声明的 JSON 字段。
		dec.DisallowUnknownFields()
	}
	if err := dec.Decode(&req); err != nil {
		// 统一返回解析错误，避免业务层拿到半成品请求。
		return OrderRequest{}, err
	}
	var tail any
	if err := dec.Decode(&tail); err != io.EOF {
		// 只接受一个 JSON 值，防止请求体尾部藏着第二段数据。
		if err == nil {
			return OrderRequest{}, errors.New("request body contains multiple JSON values")
		}
		return OrderRequest{}, err
	}
	return req, nil
}

兼容入口也要有可收紧的边界

兼容模式不是永久忽略问题。最少要把它限制在旧版本路由，并在解码完成后记录接口版本、客户端标识和未知字段名。若需要保留未知字段，可先把原始对象解码到 map[string]json.RawMessage，移除已知键后再统计剩余键；不要把整段原始 JSON 无期限写进日志。

迁移可以分三段：第一段只统计并告警，不影响请求；第二段通知调用方删除旧字段或升级 SDK；第三段在新版本入口全面启用严格校验。若某个字段只是服务端新增、旧客户端不会发送，那么它本身不会触发 unknown field；真正触发错误的是客户端发来了服务端 DTO 没声明的键。

几个容易踩到的边界

• 结构体标签会影响字段匹配，先检查 json:"..." 是否写错，不要直接关闭严格模式。
• 嵌套结构体中的未知字段同样可能触发错误，兼容策略要覆盖完整请求树。
• 严格解码不能代替业务校验；字段合法但业务状态不允许时，仍应在解码后单独判断。
• 如果接口只有一条路径，至少用明确的版本请求头或配置开关，并让开关由服务端控制、可审计、可回滚。

相关问题

旧客户端只是少传了新字段，会被拒绝吗？不会。未知字段校验针对“多传且结构体不认识”的键；缺少非必填 Go 字段通常只得到零值，是否必填要由业务层判断。

能不能在报错后自动改用宽松解码？不建议。这样会把严格校验变成可绕过的软失败。应由版本、路由或服务端策略在进入解码前确定模式，并给兼容入口设置迁移期限。