Go encoding/json.Decoder 如何控制未知字段：DisallowUnknownFields 的兼容发布策略

给一个已经运行多年的 Go HTTP 接口加字段校验时，最容易踩的坑不是不会调用 DisallowUnknownFields，而是把“客户端多传一个字段”直接等同于“请求非法”。老客户端、灰度版本和代理层都可能让未知字段先出现。更稳的做法是先明确接口的兼容边界，再决定哪些路由启用严格解码。

先看默认行为：未知字段为什么没有报错

下面这个请求多传了 trace_id，但目标结构体没有这个字段。标准库的默认解码会正常返回，Name 和 Age 仍然能拿到值：

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

var req CreateUserRequest
err := json.NewDecoder(r.Body).Decode(&req)
// {"name":"Mina","age":28,"trace_id":"a-17"} 仍可能解码成功

这种宽松行为不是漏洞，它让服务端增加可选字段时不会立即打断旧版本调用方。代价也很直接：客户端把 agge 写错时，服务端可能静默使用年龄零值，错误会拖到业务校验或数据落库才暴露。

接口目标决定是否启用 DisallowUnknownFields

如果这个接口用于配置提交、内部任务参数或需要尽快暴露拼写错误的管理入口，严格字段集合通常更合适。调用方数量多、版本跨度大，或者中间层会追加诊断字段时，直接全量切换就容易误伤。

可以先把决策写成一张小表，避免“所有接口都严格”成为没有验证的默认动作：

最小严格解码：把字段错误挡在业务逻辑之前

启用开关只需要一行，但生产代码还应限制请求体大小、检查多余 JSON 内容，并把解码错误转成稳定的客户端响应：

func decodeCreateUser(r *http.Request) (CreateUserRequest, error) {
    var req CreateUserRequest
    dec := json.NewDecoder(io.LimitReader(r.Body, 1

这里的第二次 Decode 用来拒绝一个对象后面又拼接另一个 JSON 值的请求。它和未知字段不是一回事：前者是请求体结构问题，后者是对象内的字段集合问题，错误码和日志字段可以分别处理。

错误处理要保留什么：字段名、状态码和关联号

严格模式返回的错误通常会带出未知字段名称，例如 json: unknown field "trace_id"。对调用方来说，字段名很有用；对服务端来说，完整错误文本不应该原样写入用户可见页面，更不能把原始请求体一起打进日志。

if err != nil {
    log.Printf("create-user decode failed request_id=%s err=%v", requestID, err)
    http.Error(w, "请求字段不符合接口版本", http.StatusBadRequest)
    return
}

如果需要让前端定位问题，可以在受控的错误响应中返回稳定的 request_id，并在服务端对未知字段做结构化统计。统计字段名时要注意脱敏，避免把密码、令牌等用户自定义键名当作普通业务数据长期保存。

兼容发布的顺序：观测、灰度、再收紧

已经有调用方的接口，建议按下面顺序推进。关键不是把严格开关藏起来，而是给每一步设一个能观察的结果：

1. 先保留宽松解码：记录未知字段计数、调用方版本和路由，不记录完整请求体。成功标准是能区分真实客户端字段与代理字段。
2. 按调用方灰度：只对已经升级并确认字段契约的客户端启用严格模式。成功标准是 400 比例没有出现无法解释的抬升。
3. 处理固定来源：如果某个网关会加入追踪字段，要在边界层剥离或把它纳入明确的请求结构，不要让业务 handler 猜测来源。
4. 保留回退开关：严格模式出现异常时先按路由关闭，再根据统计修复客户端或代理。回退应是配置变更，不要临时改一份结构体掩盖问题。

常见问题：严格字段校验的边界在哪里

DisallowUnknownFields 会检查 JSON 字段的类型吗？

会在解码时暴露类型不匹配，但它的主要职责是拒绝目标结构体未声明的字段。必填、范围和字段之间的业务约束仍需在解码后单独校验。

开启严格模式后还能增加可选字段吗？

可以。服务端先发布能识别新字段的版本，再让客户端发送它；顺序反过来就会让旧服务把新字段当成错误。

为什么不直接把未知字段全部丢弃？

对公共接口，丢弃未知字段能保留兼容性；对配置或管理接口，静默丢弃可能把拼写错误变成错误配置。应按调用方可控程度选择。

请求体只解码一次就够了吗？

不一定。一次解码可能接受对象后残留的第二个 JSON 值，生产入口最好再确认后续内容只有空白。

把开关放在契约边界，而不是放在情绪里

DisallowUnknownFields 适合用来尽早发现接口契约漂移，但它不是越严格越好。先看调用方是否可控、代理是否会改写请求、错误是否能被观测，再决定按路由还是全局启用。对于已有公共接口，观测和灰度比一次性切换更容易回退，也更容易解释每一个 400。