Go JSON 严格解码上线后请求变 400：DisallowUnknownFields 的兼容性故障复盘

订单接口把 JSON 解码器换成严格模式后，监控里突然多了一批 400 请求，服务端日志却只显示“unknown field”。表面看像是客户端发错了请求，真正的触发点是旧客户端携带了服务端暂时不用的扩展字段，而 DisallowUnknownFields 把原本可以自动忽略的字段直接判定成了协议错误。这个选项本身适合收紧接口边界，但不适合没有提前做兼容策略的情况下，直接覆盖所有存量客户端。

400 是从哪一个请求开始出现的

故障现场可以压缩成一段很小的复现代码。服务端原先使用 json.NewDecoder(r.Body).Decode(&req)，客户端多传一个字段不会影响已声明字段的正常读取；后来为了防止字段拼写错误，新增了 decoder.DisallowUnknownFields() 配置。

type CreateOrderRequest struct {
    UserID int    `json:"user_id"`
    Amount int64  `json:"amount"`
}

func decodeOrder(body io.Reader) (CreateOrderRequest, error) {
    var req CreateOrderRequest
    decoder := json.NewDecoder(body)
    decoder.DisallowUnknownFields()
    err := decoder.Decode(&req)
    return req, err
}

下面这个请求在宽松模式下可以正常创建订单，切换到严格模式就会直接解码失败：

{"user_id": 42, "amount": 1999, "coupon_code": "JULY26"}

coupon_code 没有出现在 Go 结构体的定义里，抛出的错误通常是 json: unknown field "coupon_code"。这不属于 JSON 格式错误，也不是金额之类的参数类型错误，本质是字段集合的兼容性不匹配。排查时先把错误类型分清楚，能少走一轮没必要的网络链路和数据库校验。

时间线里真正的触发条件是额外字段

这类事故很容易被误判成“新代码把所有请求都拒绝了”。复盘时把发布动作、客户端升级进度和请求体特征放在同一条时间线对应核对：

这个阶段别急着修改数据库或者加重试次数。重试没办法修复已经不符合要求的请求体，反而可能放大无效的 400 日志。更有价值的操作是记录下客户端版本、接口版本、未知字段名和请求关联 ID；生产环境不要记录完整的支付信息或者用户隐私字段。

为什么严格校验会误伤本来合法的客户端

JSON 接口的兼容性不只是由服务端结构体定义单方面决定。移动端经常会先上线新字段，服务端后续版本才会识别它；反向代理、BFF 或者实验开关也可能把新增的扩展字段透传到下游服务。宽松解码的代价是字段拼写错误很难被提前发现，严格解码的代价则是“新增字段”这个原本兼容的变化，变成了破坏性的协议不兼容。

不同场景的决策边界可以参考下面这些规则：

• 内部、版本同步的接口：客户端和服务端一起发布，严格模式更容易管控。
• 公开或跨团队接口：优先按接口版本做隔离，不能把新校验直接覆盖到旧版本接口。
• 需要拒绝未知字段的安全场景：保留严格模式，但要提供明确的错误字段提示和灰度观测环节。
• 只想发现拼写错误的场景：先在日志或者测试环境里上报未知字段，不要直接把请求判定成 400 错误。

修复方案：把严格边界放到可控的版本里

最小修复方案不是永久删除严格校验，而是让它只作用于已经提前声明兼容契约的新接口。比如把旧的 /api/orders 保持原有兼容逻辑，新接口 /api/v2/orders 再启用严格解码。如果暂时不能拆分版本，可以先按客户端版本做灰度，同时在错误响应里返回稳定的业务错误码。

type DecodeError struct {
    Field string `json:"field"`
    Code  string `json:"code"`
}

func decodeStrict(body io.Reader) (CreateOrderRequest, *DecodeError) {
    var req CreateOrderRequest
    decoder := json.NewDecoder(body)
    decoder.DisallowUnknownFields()
    if err := decoder.Decode(&req); err != nil {
        var field string
        if n, ok := err.(*json.UnmarshalTypeError); ok {
            field = n.Field
        }
        return req, &DecodeError{Field: field, Code: "invalid_request"}
    }
    return req, nil
}

上面的示例只识别了常规的类型错误，未知字段错误仍建议在 HTTP 层保留原始错误文本中的字段名，经过脱敏后再写入日志。真正上线前要补全对应的测试用例：已知字段正常传参、携带未知字段、字段类型错误、空请求体、尾部多余 JSON，以及不同客户端版本的真实请求样本。

上线前用一组请求把边界锁住

测试用例不需要做的很庞大，关键是让协议校验的决策逻辑可以稳定复现。下面的检查清单适合放进接口回归用例集：

1. 只发送 user_id 和 amount，接口应返回成功。
2. 增加 coupon_code，旧接口按兼容策略处理，新接口按契约返回明确错误。
3. 把 amount 改成字符串类型，确认类型错误与未知字段错误不会混为一谈。
4. 在完整 JSON 内容后追加第二个对象，确认读取策略和日志行为符合接口约定。
5. 使用上一版移动端、BFF 和历史回放请求做灰度验证，观察 400 占比和未知字段的分布情况。

如果历史请求里未知字段的数量很多，可以先做一个字段统计榜单：按字段名、客户端版本、接口版本和出现次数做聚合。高频出现的字段往往不是恶意攻击，而是已经线上存在但没有写进服务端契约的产品需求。把它们直接判定成错误，相当于把兼容性问题直接推给线上用户承担。

相关问题

DisallowUnknownFields 会检查 JSON 数组里的对象吗？

会。只要对象最终被解码到对应的结构体，数组元素中的未知字段同样可能触发错误。

只使用 json.Unmarshal 能开启同样的严格校验吗？

不能直接调用同名选项。需要使用 json.Decoder，在 Decode 前调用 DisallowUnknownFields。

旧客户端已经带了新字段，应该立刻回滚吗？

先确认 400 是否全部集中在未知字段场景，再根据接口是否有版本边界决定后续动作。公开接口通常先恢复兼容或者切换灰度，同时保留字段观测逻辑，比盲目全量回滚更容易收敛问题。

把“更严格”变成可发布的协议变化

DisallowUnknownFields 本身没有问题，问题在于把它当成了不需要评审的普通代码重构。它改变了服务端对字段集合的接受范围，应该像接口版本升级一样准备好验证样本、灰度方案和回滚点。先定位所有存量未知字段，再选择版本隔离、灰度校验或者日志告警的方案，既能达到发现拼写错误的目的，也不会因为一个校验开关误伤仍在运行的旧客户端。