encoding/json/v2 的未知字段处理与兼容策略

同一个 JSON 请求被新旧客户端共同使用时，真正需要先决定的不是“字段要不要加”，而是未知成员应该被忽略、拒绝，还是原样保留。encoding/json/v2 的默认行为适合向前兼容：目标结构体没有对应字段的成员会被忽略；需要严格契约时使用 json.RejectUnknownMembers(true)；需要把扩展交给下一层时，则给结构体加一个 json:",embed" 的 fallback 字段。

先按业务语义分三类未知字段

配置对象通常允许新版本增加字段，旧服务只消费自己认识的部分，此时未知成员应该忽略。鉴权、计费或写入数据库的命令对象则更适合严格拒绝，避免调用方把拼写错误当成已生效参数。还有一类是网关、插件宿主或协议中转层：它们不一定理解扩展字段，却必须把字段转发给下一跳，这时丢弃数据同样会破坏兼容性。

默认解码适合新旧客户端并行

下面的请求结构只认识 name 和 timeout。即使输入多出 traceMode，v2 也会继续填充已知字段。这个策略的重点是“忽略但不承诺保留”：如果后续要重新编码请求，未知成员不会凭空出现在输出里。

package main

import (
    "fmt"
    "log"

    "encoding/json/v2"
)

type CreateJob struct {
    // Name 是旧服务真正消费的稳定字段。
    Name string `json:"name"`
    // Timeout 只描述本服务能够执行的超时范围。
    Timeout int `json:"timeout"`
}

func main() {
    // 新客户端增加 traceMode，旧结构体会按默认规则忽略它。
    input := []byte(`{"name":"build","timeout":30,"traceMode":"sampled"}`)
    var job CreateJob
    if err := json.Unmarshal(input, &job); err != nil {
        log.Fatal(err)
    }
    // 这里只能确认已知字段，不能声称 traceMode 被保留。
    fmt.Printf("%s %d\\n", job.Name, job.Timeout)
}

适合把默认策略放在读取“可扩展请求”的边界。若字段拼写错误会被静默忽略，就应该把严格检查放到更窄的命令或配置入口，而不是对所有消息全局开启。

严格接口用 RejectUnknownMembers 定位错误

严格模式通过选项传给解码函数，而不是写进结构体标签。官方 API 将未知成员包装为 SemanticError，底层原因是 ErrUnknownName，同时可从 JSONPointer 取得未知键。这样日志可以记录字段路径，调用方则可以收到稳定的参数错误。

package main

import (
    "errors"
    "fmt"

    "encoding/json/v2"
)

type UpdateJob struct {
    // ID 和 Enabled 是更新命令允许出现的字段。
    ID      string `json:"id"`
    Enabled bool   `json:"enabled"`
}

func decodeStrict(input []byte) error {
    var cmd UpdateJob
    // 严格模式只作用于本次解码，不会改变 Marshal 的行为。
    err := json.Unmarshal(input, &cmd, json.RejectUnknownMembers(true))
    if err == nil {
        return nil
    }

    // 只有严格拒绝未知成员时，ErrUnknownName 才会出现在 SemanticError 中。
    if serr, ok := errors.AsType[*json.SemanticError](err); ok && serr.Err == json.ErrUnknownName {
        return fmt.Errorf("不支持的字段 %q: %w", serr.JSONPointer.LastToken(), err)
    }
    return err
}

这里不要只比较错误字符串。JSON Pointer 比“unknown field”更适合嵌套对象和机器日志；但严格模式仍然解决不了版本协商问题，客户端需要先知道服务端允许哪些字段。

需要透传时使用 embedded fallback

如果未知成员要进入插件配置或转发到下一服务，可以用 map[string]jsontext.Value 作为嵌入式 fallback。v2 文档把这种字段定义为承接父对象中未被显式字段处理的成员；它与“默认忽略”不同，因为原始 JSON 值会进入扩展集合。

package main

import (
    "encoding/json/jsontext"
    "encoding/json/v2"
)

type Envelope struct {
    // Version 是网关自己理解的协议字段。
    Version int `json:"version"`
    // Extra 接住未匹配成员，供下一层按原始 JSON 值继续处理。
    Extra map[string]jsontext.Value `json:",embed"`
}

func decodeEnvelope(input []byte) (Envelope, error) {
    var env Envelope
    // embed fallback 不能再搭配 JSON 名称或其他标签选项。
    err := json.Unmarshal(input, &env)
    return env, err
}

透传方案要单独设计冲突规则：扩展键不能覆盖 version 等已知字段，只有一个 embedded fallback，且下一层仍应对扩展字段做自己的校验。不要因为能保留未知字段，就把不可信输入直接当成已验证配置。

把兼容策略放进版本发布清单

接口从宽松切换到严格时，先统计旧客户端实际发送的字段，再灰度打开拒绝策略；如果需要透传，优先明确扩展字段的命名空间和大小上限。回归时至少覆盖“旧客户端发旧字段、新客户端发新增字段、拼写错误、嵌套未知成员、已知字段与 fallback 键冲突”五种样例。

• 读取型 API：默认忽略，文档说明未知字段不会回写。
• 写入型命令：在边界处启用严格拒绝，并把 JSONPointer 写入可观测日志。
• 中转型对象：使用 fallback 保留扩展，但在转发前限制键名、值大小和冲突行为。

常见问题

默认忽略未知字段会返回错误吗？

不会。只有传入 json.RejectUnknownMembers(true) 时，未知成员才会触发 SemanticError。

严格模式会影响 JSON 编码吗？

不会。RejectUnknownMembers 只影响 unmarshaling，调用 Marshal 时不参与编码决策。

为什么不用 map[string]any 保存扩展字段？

jsontext.Value 更贴近原始 JSON 值，避免先把数字等内容泛化为不合适的 Go 类型；是否转成业务类型应由下一层决定。

选择未知字段策略时，先问清楚数据是“可忽略、必须拒绝，还是需要转发”。这三个答案分别对应默认解码、RejectUnknownMembers 和 embedded fallback；兼容性问题通常不是换一个标签就结束，而是要把版本协商、错误路径和扩展边界一起写进接口契约。