Go json.Decoder保留未知字段兼容升级的结构设计

服务端收到新版客户端 JSON 时，最怕的不是多一个字段，而是旧版本把这个字段悄悄丢掉，升级后又无法判断它是否值得继续传递。Go json.Decoder 解码结构体时，默认会忽略没有对应字段的键；这正好适合向前兼容，但如果业务要求“先保留、后识别”，就要为未知字段设计独立的存放位置。

先确认 Decoder 的默认边界

官方 encoding/json 文档说明：JSON 对象解码到 Go 结构体时，没有对应结构体字段的键默认会被忽略；DisallowUnknownFields 会改变这个行为，让未知键返回错误。因此，兼容升级不应一上来就开启严格模式，否则新客户端增加可选字段会被旧服务拒绝。

package main

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

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

func decodeCompatible(input string) error {
    var p Profile
    dec := json.NewDecoder(strings.NewReader(input))
    if err := dec.Decode(&p); err != nil {
        // 已知字段类型错误仍然要返回，兼容只针对未知字段。
        return err
    }
    fmt.Printf("name=%s age=%d\n", p.Name, p.Age)
    return nil
}

用 RawMessage 把未知字段单独保留下来

如果只是忽略未知字段，直接解码结构体即可；如果还要把它们转发、落库或等待下一版本解释，可以先把整个对象解码为 map[string]json.RawMessage，再把已知键解码到结构体。RawMessage 保存的是原始 JSON 片段，字符串、数字、数组和对象都不会在收集阶段被强行转换。

type Envelope struct {
    Profile  Profile
    Extra    map[string]json.RawMessage
}

func decodeWithExtra(input string) (Envelope, error) {
    var fields map[string]json.RawMessage
    if err := json.Unmarshal([]byte(input), &fields); err != nil {
        // 顶层不是合法 JSON 对象时，不能进入字段分流阶段。
        return Envelope{}, err
    }

    var result Envelope
    known := map[string]bool{"name": true, "age": true}
    for key, raw := range fields {
        if known[key] {
            // 已知字段仍交给标准解码，保留类型错误信息。
            continue
        }
        if result.Extra == nil {
            // 延迟创建，避免没有扩展字段时额外分配 map。
            result.Extra = make(map[string]json.RawMessage)
        }
        result.Extra[key] = raw
    }

    knownJSON := make(map[string]json.RawMessage, len(fields)-len(result.Extra))
    for key, raw := range fields {
        if known[key] {
            knownJSON[key] = raw
        }
    }
    if err := json.Unmarshal(mustJSON(knownJSON), &result.Profile); err != nil {
        // 只允许未知字段兼容，已知字段类型变化仍应阻断请求。
        return Envelope{}, err
    }
    return result, nil
}

func mustJSON(v any) []byte {
    data, err := json.Marshal(v)
    if err != nil {
        // 这里的 map 值都来自合法 JSON，失败属于不可恢复的内部错误。
        panic(err)
    }
    return data
}

上面的分流适合对象级扩展字段。若只需要把未知字段原样透传，也可以让结构体实现 UnmarshalJSON，在一个自定义方法中完成“别名结构体 + 原始 map”的两次视图转换。注意不要在自定义方法里再次直接解码到自身，否则会递归调用。

兼容字段与严格字段要分层

兼容升级解决的是“新字段不应让旧服务失败”，并不表示所有字段都可信。常见做法是：公共入口用默认 Decoder 接受可选扩展；核心业务字段继续检查类型、范围和必填关系；内部配置、契约测试或迁移脚本使用严格 Decoder，尽早发现拼写错误。

func decodeStrict(input string) error {
    var p Profile
    dec := json.NewDecoder(strings.NewReader(input))
    dec.DisallowUnknownFields()
    if err := dec.Decode(&p); err != nil {
        // 严格模式适合契约检查，不宜无条件放在所有公网入口。
        return fmt.Errorf("strict decode: %w", err)
    }
    return nil
}

用测试覆盖升级边界

至少准备四组输入：只有旧字段、增加可选字段、已知字段类型错误、嵌套扩展字段。检查结果时不要只比较结构体；还要确认 Extra 中的原始片段没有被提前转成浮点数或丢失数组层级。扩展字段若会落库或转发，还应设置单字段和总请求大小上限。

func TestCompatibleUpgrade(t *testing.T) {
    input := `{"name":"Ada","age":36,"theme":{"mode":"dark"}}`
    got, err := decodeWithExtra(input)
    if err != nil {
        // 新增扩展字段不应影响旧版核心字段。
        t.Fatal(err)
    }
    if got.Profile.Name != "Ada" || len(got.Extra) != 1 {
        // 同时确认已知字段和未知字段都被保留在正确位置。
        t.Fatalf("unexpected decode: %#v", got)
    }
}

官方地址：https://pkg.go.dev/encoding/json

相关问题

未知字段应该直接丢弃吗

不需要转发或审计时可以丢弃；要做灰度升级、事件回放或跨版本转发时，建议以 json.RawMessage 原样保存。

开启 DisallowUnknownFields 能检查字段类型吗

它主要拒绝未知键，已知字段的类型错误仍由正常解码流程返回；两类错误应分别记录和处理。

为什么不直接使用 map[string]any

map[string]any 会把数字等值转换为通用类型，扩展字段的原始表示和后续再编码结果可能改变；RawMessage 更适合延迟解释。