Go DisallowUnknownFields 为什么只报告首个未知字段

Decoder.DisallowUnknownFields() 只报告一个未知字段，并不是漏检。它的公开职责是：目标为结构体时，只要输入对象含有无法匹配非忽略、已导出字段的键，就让 Decode 返回错误；它没有承诺收集全部未知字段。当前实现会保存遇到的第一个解码错误，后面的未知字段不会替换它。

先区分拒绝请求和批量提示

这两个需求看起来相近，处理成本却不同。API 网关只要判断请求是否合格，返回一个明确的未知字段通常就够了；表单或配置编辑器希望用户一次改完，才需要完整的字段列表。DisallowUnknownFields 面向前一种严格解码，不是 JSON 校验报告器。

官方文档的措辞也是“return an error”，不是“return all errors”。因此，不要通过解析错误字符串或重复删除字段来凑列表；这会绑定内部错误格式，也会让嵌套对象和重复键变得难以维护。

首个错误来自 savedError

解码对象时，encoding/json 会用输入键查找结构体字段。找不到字段且启用了 disallowUnknownFields 时，解码器创建 json: unknown field ... 错误，并交给内部的 saveError。该方法只在保存槽为空时写入，所以第一个错误留下，后续错误不再覆盖。解码仍会消费输入，最后返回已经保存的错误。

“首个”更准确地说是当前实现按输入解析时首先保存的错误。应用不应依赖具体字段顺序，因为标准库契约没有把“返回哪一个未知字段”定义成稳定的业务规则。

严格接口直接返回一个错误

对于创建订单、修改资料这类接口，一个错误就足以拒绝请求。除了启用未知字段检查，还应确认正文只包含一个 JSON 值，避免第一个对象后面跟着额外内容。

func decodeCreateUser(r io.Reader) (CreateUser, error) {
    var req CreateUser
    dec := json.NewDecoder(r)
    dec.DisallowUnknownFields() // 未声明字段立即进入解码错误

    if err := dec.Decode(&req); err != nil {
        return CreateUser{}, fmt.Errorf("invalid request: %w", err)
    }

    var extra any
    if err := dec.Decode(&extra); err != io.EOF {
        return CreateUser{}, errors.New("request must contain one JSON value") // 拒绝尾随对象
    }
    return req, nil
}

这种方案的优势是简单：结构体就是允许字段清单，类型转换与未知字段检查在同一次 Decode 中完成。代价是客户端每次只能修复当前返回的一个问题。

需要一次列全就预扫描顶层键

如果产品明确要求一次显示全部顶层未知字段，可以先把同一份 JSON 解析为 map[string]json.RawMessage，与允许字段集合比较；没有未知键后，再严格解码到结构体。排序可让错误输出稳定，便于测试和前端展示。

func unknownTopLevel(data []byte, allowed map[string]struct{}) ([]string, error) {
    var fields map[string]json.RawMessage
    if err := json.Unmarshal(data, &fields); err != nil {
        return nil, err // 语法错误先交给标准库处理
    }

    unknown := make([]string, 0)
    for name := range fields {
        if _, ok := allowed[name]; !ok {
            unknown = append(unknown, name) // 只收集当前对象的顶层键
        }
    }
    sort.Strings(unknown) // 让返回顺序稳定
    return unknown, nil
}

func decodeProfile(data []byte) (Profile, error) {
    allowed := map[string]struct{}{"name": {}, "email": {}}
    unknown, err := unknownTopLevel(data, allowed)
    if err != nil {
        return Profile{}, err
    }
    if len(unknown) > 0 {
        return Profile{}, fmt.Errorf("unknown fields: %s", strings.Join(unknown, ", "))
    }

    var dst Profile
    dec := json.NewDecoder(bytes.NewReader(data))
    dec.DisallowUnknownFields() // 二次严格解码继续检查类型和结构
    if err := dec.Decode(&dst); err != nil {
        return Profile{}, err
    }
    return dst, nil
}

这段辅助函数只解决顶层对象。嵌套结构、数组元素、字段别名和自定义 UnmarshalJSON 都会增加复杂度，不能把它宣传成通用 JSON Schema 校验。

嵌套对象应使用模式校验

Decode 返回首个未知字段后，目标结构体还能使用吗？

不建议继续用于业务。解码过程中部分已知字段可能已经写入，但整体请求已失败；应丢弃结果并返回错误。

能否循环调用 Decode 得到下一个未知字段？

不能。一次 Decode 已经消费完整 JSON 值，第二次 Decode 面向下一个 JSON 值，而不是继续报告同一个对象里的错误。

官方参考：https://pkg.go.dev/encoding/json