Go 问答：json.Decoder.DisallowUnknownFields 什么时候开启：兼容新增字段还是严格拒绝

接口刚加了一个可选字段，旧客户端却开始收到 400，这类回归通常不是 JSON 语法错了，而是服务端把未知字段当成了错误。json.Decoder 默认会忽略结构体没有声明的键；只有显式调用 DisallowUnknownFields，才会在结构体解码时拒绝未知字段。是否开启，关键看这个入口是在接收会持续演进的业务协议，还是在守住字段拼写和配置边界。

对公开、需要向前兼容的请求，默认忽略未知字段更稳；对内部管理接口、配置文件和希望尽早暴露拼写错误的入口，可以开启 DisallowUnknownFields，但要配合版本策略或灰度。

默认行为为什么容易让字段拼写错误悄悄通过

假设服务端只定义了 User 的 name 字段，客户端却发送了 naem。普通解码不会因为这个键没有对应字段而报错，User.Name 仍然保持零值。对长期演进的接口，这是兼容性；对配置或管理接口，这又可能把一个低级拼写错误拖到后面的业务判断里。

最小严格解码：把 unknown field 变成可见信号

package main

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

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

func decodeCreateUser(body string) error {
    var in CreateUser
    dec := json.NewDecoder(strings.NewReader(body))
    dec.DisallowUnknownFields()
    if err := dec.Decode(&in); err != nil {
        return fmt.Errorf("decode create user: %w", err)
    }
    fmt.Printf("name=%s age=%d\n", in.Name, in.Age)
    return nil
}

输入 {"name":"Lin","age":20,"agge":21} 时，错误会包含 json: unknown field "agge"。这里的检查点是 dec.DisallowUnknownFields() 必须出现在 Decode 之前；它不是对已经解码完成的结构体做事后扫描。

开启严格模式前，先判断协议是不是会向前兼容

严格模式最常见的误用，是把所有 HTTP 请求都当成配置文件处理。移动端或第三方客户端可能先发出新字段，旧服务端如果立即拒绝，升级顺序就会变成线上故障。此时可以保留宽松入口，或者把新协议放到新版本路径中，例如 /v2/users，让兼容边界显式存在。

如果入口是团队控制的内部后台，字段集合变化通常伴随同一批代码发布，未知字段反而值得尽早失败。错误应该记录请求路径和字段名，但不要把敏感请求体完整写入日志。

几个容易误判的边界

它会检查所有 JSON 层级吗

它针对目标结构体解码时遇到的未知对象键。嵌套结构体也应按实际目标类型观察错误，但把它当成完整的字段约束系统并不准确；数组、map[string]any 或自定义 Unmarshaler 仍要分别核对。

加了 json 标签后就一定严格了吗

不会。json:"name" 只定义键名映射；是否拒绝其他键，仍由 DisallowUnknownFields 决定。默认解码仍会忽略没有对应字段的键。

能不能只忽略一个已知扩展字段

严格模式没有按字段白名单逐个放行的参数。需要兼容扩展时，可以在协议层保留一个明确的扩展对象，或先做版本化，而不是在错误后再猜哪些字段应该放过。

上线前用三组输入做回归

至少准备三组固定样例：只有 name 和 age 的合法输入、带 agge 的未知字段输入、以及缺少业务必填字段的输入。第一组应成功，第二组在严格入口返回 unknown field，第三组还需要由业务校验判断，不能把“字段存在”误当成“值有效”。

如果接口要从宽松模式迁移到严格模式，先在日志或指标中统计未知字段，再按客户端版本分批切换。这样能区分“调用方真的发错了”与“服务端提前拒绝了合法的新字段”。

相关问答：DisallowUnknownFields 怎么选

它适合所有 POST 接口吗

不适合。公开接口更需要考虑客户端先升级的情况；配置、内部后台和受控服务间协议通常更适合严格模式。

未知字段错误能直接返回给用户吗

可以返回字段名和参数位置，但不要回显完整请求体。对外接口还应统一错误结构，避免把 Go 内部错误文本当成长期 API 契约。

严格解码能替代必填校验吗

不能。它解决的是“多了未声明字段”，不解决“字段缺失、值为空、范围不合法”或字段之间的业务约束。

把选择落到入口的生命周期上

最终判断很简单：协议要吸收未来字段，就保留兼容；协议由同一团队控制且拼写错误的代价更高，就在 Decode 前开启严格模式。无论选择哪一种，都用固定样例验证合法输入、未知字段和业务缺失三条路径，别让一次开关决定了整套接口的兼容策略。