Go json.Decoder 输入未知字段如何兼容灰度客户端

灰度客户端给请求 JSON 增加字段时，Go 的 json.Decoder 默认不会因为“目标结构体没有这个字段”而失败。这个行为正适合向前兼容：旧服务端可以先忽略新字段，让新旧客户端同时在线。真正需要收紧时，再只对内部校验入口调用 DisallowUnknownFields()，不要把它无条件放进所有公共接口。

兼容灰度客户端的最小做法是保留默认宽松解码；未知字段必须被拒绝时，才在明确的内部或已完成迁移的入口启用严格解码。

先分清未知字段与类型错误

假设服务端当前只认识 name 和 enabled，灰度客户端多发了 trace_id。下面的结构体没有定义这个字段，但解码仍然可以成功；如果客户端把 enabled 从布尔值改成字符串，则会得到类型错误，这不能靠“忽略未知字段”解决。

package main

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

type Request struct {
    Name    string `json:"name"`
    Enabled bool   `json:"enabled"`
}

func main() {
    input := `{"name":"gray-client","enabled":true,"trace_id":"t-42"}`
    var req Request
    // 默认 Decoder 会忽略结构体未声明的 trace_id，但仍检查 enabled 的类型。
    err := json.NewDecoder(strings.NewReader(input)).Decode(&req)
    if err != nil {
        // 生产接口应把解析错误转换为稳定的 4xx 响应，避免继续使用半成品。
        panic(err)
    }
    fmt.Printf("name=%s enabled=%t\n", req.Name, req.Enabled)
}

这段示例的结果只说明已知字段成功进入结构体，并不表示服务端保存了 trace_id。如果扩展字段有业务价值，应显式设计字段，而不是依赖“未知字段恰好被忽略”。

公共兼容入口应保持宽松

灰度发布最常见的约束是“客户端先升级，服务端不能立刻拒绝”。服务端可以让公共请求结构体只承载稳定字段，同时把扩展能力单独建模。这样做的重点不是吞掉所有错误，而是只对字段集合放宽，对 JSON 语法、字段类型和业务必填项继续检查。

若需要保留未识别字段用于审计，可以先解码到 map[string]json.RawMessage，再取出已知键；但这会增加类型判断和内存成本。只有确实需要转发或记录原始扩展时才值得这样做。

严格校验放在可控的收紧入口

DisallowUnknownFields 会让目标是结构体的 JSON 对象在遇到没有对应导出字段的键时返回错误。它适合测试契约、内部调用和迁移完成后的入口。一个小型服务可以把策略作为参数传入，灰度期间默认关闭，切换后再打开。

func decodeRequest(body io.Reader, strict bool) (Request, error) {
    var req Request
    dec := json.NewDecoder(body)
    if strict {
        // 严格模式只给已完成迁移的流量使用，避免误伤旧客户端。
        dec.DisallowUnknownFields()
    }
    if err := dec.Decode(&req); err != nil {
        // 返回错误前不要继续执行后续业务，也不要复用不完整的 req。
        return Request{}, fmt.Errorf("decode request: %w", err)
    }
    return req, nil
}

示例依赖 io、json、fmt 和前面的 Request 定义。实际 HTTP handler 还应限制请求体大小，并决定是否检查第二个 JSON 值；这些属于接口边界，不应由未知字段策略代替。

用发布清单决定什么时候收紧

不要根据某一次请求“看起来没有未知字段”就全局打开严格模式。更稳的顺序是：先记录未知字段名、客户端版本和接口路径；确认旧版本流量已经低于可接受阈值；为严格开关准备回滚；再在内部流量和小比例灰度中观察错误率。收紧后如果出现 json: unknown field，优先定位仍在发送旧契约的调用方，而不是删除服务端字段来躲避错误。

• 兼容阶段：默认解码，明确记录扩展字段，已声明字段照常校验。
• 过渡阶段：内部或测试入口严格，公共入口仍宽松，比较两条路径的拒绝率。
• 稳定阶段：迁移完成的接口可严格，仍需支持的老接口保持版本化兼容。

这样，json.Decoder 的默认行为就成为发布策略的一部分，而不是一个隐藏副作用：新增字段不会阻断灰度，拼写错误也能在适合的边界被发现。

常见问题

调用 Decode 会自动拒绝未知字段吗？

不会。目标是结构体时，默认会忽略没有匹配字段的 JSON 键；只有显式调用 DisallowUnknownFields 才会拒绝。

未知字段被忽略后还能拿回来吗？

直接解码到结构体后通常拿不到。若必须保留扩展，应显式使用 map[string]json.RawMessage 或在结构体中设计扩展字段。

严格模式能检查字段是否必填吗？

不能。它主要检查未知字段；必填、取值范围和跨字段关系仍需要单独的业务校验。