Go JSON 解码如何保留未知字段：结构体校验、RawMessage 与兼容升级

接口升级时，最容易被忽略的不是字段新增，而是“未知字段到底该不该报错”。直接用 json.Unmarshal，拼错的字段会被静默忽略；一上来就启用严格解码，又可能把新客户端发来的扩展字段全部挡掉。更稳的做法是把结构体校验和原始 JSON 保留拆成两条路径：核心请求严格检查，扩展区域交给 json.RawMessage 延后处理。

先把“未知字段”分成两类

线上常见的两种未知字段，处理方向正好相反。用户把 timeuot 写错，本来应该被立即指出；服务端未来新增 trace 或实验性配置时，旧客户端则最好继续工作。

因此不要把“严格”理解成整个 JSON 文档只有一个开关。请求入口可以严格，扩展对象可以宽松；响应读取可以兼容，配置文件可以拒绝未知键。这个边界要写在接口契约里，而不是让每个调用方猜。

严格解码：让拼写错误在入口处暴露

如果请求字段集合是稳定的，可以给 json.Decoder 开启 DisallowUnknownFields。它会在目标结构体没有对应字段时返回错误，嵌套结构也会参与检查。

type CreateJobRequest struct {
    Name   string `json:"name"`
    Queue  string `json:"queue"`
    Labels map[string]string `json:"labels"`
}

func decodeCreateJob(r io.Reader) (CreateJobRequest, error) {
    var req CreateJobRequest
    dec := json.NewDecoder(r)
    dec.DisallowUnknownFields()
    if err := dec.Decode(&req); err != nil {
        return CreateJobRequest{}, fmt.Errorf("decode create job: %w", err)
    }
    return req, nil
}

传入 {"name":"build","queue":"fast","quue":"fast"} 时，调用方会得到未知字段错误，而不是创建一个缺少队列信息的任务。这里还应该检查请求体后面是否有第二个 JSON 值，避免把拼接的额外内容悄悄放过去：

if err := dec.Decode(&struct{}{}); err != io.EOF {
    return CreateJobRequest{}, errors.New("request body must contain one JSON value")
}

兼容扩展：用 RawMessage 留住还不认识的部分

严格解码不适合所有接口。比如任务请求有一段按队列类型变化的 options，主服务只负责路由，真正的字段由队列处理器解释。这时可把扩展字段声明为 json.RawMessage，先保留原始字节，再根据 queue 选择具体结构。

type SubmitRequest struct {
    Queue   string          `json:"queue"`
    Payload json.RawMessage `json:"payload"`
}

func decodePayload(req SubmitRequest) (any, error) {
    switch req.Queue {
    case "email":
        var p EmailPayload
        if err := json.Unmarshal(req.Payload, &p); err != nil {
            return nil, fmt.Errorf("decode email payload: %w", err)
        }
        return p, nil
    case "report":
        var p ReportPayload
        if err := json.Unmarshal(req.Payload, &p); err != nil {
            return nil, fmt.Errorf("decode report payload: %w", err)
        }
        return p, nil
    default:
        return nil, fmt.Errorf("unsupported queue %q", req.Queue)
    }
}

RawMessage 不是“跳过校验”。它只是把校验时间推迟了：处理器仍要检查必填字段、类型、范围和是否有尾随内容。若扩展区允许任意键，也要在文档中说明哪些键会被保存、哪些键会被丢弃。

把解码流水线放进可复查的门禁

我更建议把入口分成四步，每一步都留下可测试的结果。

1. 读取：限制请求体大小，创建一个新的 Decoder，不要复用已经读过的流。
2. 核心校验：稳定字段使用严格解码；必填字段再做空值和范围判断。
3. 扩展分派：依据版本或类型解析 RawMessage，把错误带上扩展名。
4. 结果核对：测试错误字段、未知扩展、空 payload、类型错误和第二个 JSON 值。

这条流水线的关键不是代码多，而是错误位置清楚。入口报“未知字段”说明请求契约错了；扩展处理器报“payload 类型错误”说明路由成功但数据不符合具体版本。

几种看似能用、实际上容易埋坑的写法

只用 Unmarshal，然后靠业务字段判断

这种方式兼容性很好，却无法发现拼写错误。配置接口尤其不适合这样做，因为调用方看到的是成功响应，实际配置可能一直使用默认值。

全局开启严格模式，再把扩展字段删掉

这会把版本演进变成强耦合升级。只要新增字段先到达旧服务，旧服务就返回错误。更合适的分层是核心字段严格、明确声明的扩展容器宽松。

RawMessage 解码后不做空值检查

空对象、JSON null 和字段缺失可能代表三种不同语义。若业务只接受完整对象，必须在二次解码后检查指针、必填字符串和集合长度，不能只看 json.Unmarshal 是否返回错误。

测试要覆盖兼容和拒绝两条路

最小测试集可以直接围绕请求样例写表格驱动测试：

tests := []struct {
    name string
    body string
    wantErr bool
}{
    {"valid core", `{"name":"build","queue":"fast"}`, false},
    {"typo field", `{"name":"build","quue":"fast"}`, true},
    {"unknown extension", `{"queue":"email","payload":{"priority":2}}`, false},
    {"second value", `{"name":"build"}{"name":"other"}`, true},
}

测试名称要说明兼容意图。尤其是“未知扩展”不能只断言不报错，还要断言原始内容确实交给了正确的处理器；否则测试可能只是验证了一个空分支。

相关问答

DisallowUnknownFields 会检查嵌套对象吗？

目标是结构体时会继续检查嵌套结构体字段；映射类型的键不是结构体字段，因此不会按同样规则限制。

RawMessage 会复制一份 JSON 吗？

解码到 RawMessage 后，标准库会保存对应 JSON 数据的副本。它适合延后解析，但不代表可以省略大小限制和业务校验。

公共 API 应该严格拒绝所有新字段吗？

没有统一答案。稳定请求、配置文件和安全敏感字段适合严格；长期演进的扩展对象可以保留未知字段，但要规定版本、存储和错误回传边界。

小结

Go 的 JSON 解码不只是“能不能反序列化”的问题，而是接口演进时谁负责理解字段。把稳定核心交给严格解码，把有版本边界的扩展交给 RawMessage，再用测试核对拒绝与兼容两条路径，既能尽早发现拼写错误，也不会因为一次字段新增就迫使所有客户端同步升级。