Go json.Decoder 读取后字段为空的排查清单

Go json.Decoder 读取后字段为空，我会先检查 Decode 返回的错误，再核对字段是否导出、JSON 标签是否对应实际键、目标层级是否一致，以及 Reader 是否已被读过。最后才判断空值是不是输入原本缺失、为 null 或为空字符串。只看到字段零值，不能证明解码器没有工作。

本文讨论 encoding/json 的传统接口，不混用 json/v2 的规则。官方文档地址：https://pkg.go.dev/encoding/json。这里没有某次生产故障或升级的实测记录；我的取舍是先改变诊断方式，再决定是否收紧接收策略，不把空字段直接归因于版本变化。

先改变看错误的方式，而不是先换 JSON 库

我不建议把“能编译、没有 panic”和“解码成功”混在一起。把 Decode 返回值丢掉，再打印结构体，很容易把类型错误、空流和映射问题都看成同一个空字符串。若返回错误，先处理错误，不继续使用可能只写入了一部分的对象。

下面把最小读取函数放在 decode.go。这个函数用于诊断单个输入值，不是完整 HTTP 请求协议处理器，不检查后面是否还有第二个 JSON 值，也不设置请求体大小限制；这些职责由调用方按协议决定。

package decodecheck

import (
    "encoding/json"
    "errors"
    "fmt"
    "io"
)

// Payload 的字段必须导出；标签与协议中的键保持一致。
type Payload struct {
    DisplayName string  `json:"display_name"`
    Alias       *string `json:"alias"`
}

// ReadPayload 只解码第一个 JSON 值；不负责关闭调用方的 Reader。
func ReadPayload(r io.Reader) (Payload, error) {
    var out Payload // 每次使用新对象，不把旧值带入缺失字段。
    dec := json.NewDecoder(r)
    dec.DisallowUnknownFields() // 严格诊断策略，使用前要考虑兼容性。
    if err := dec.Decode(&out); err != nil {
        if errors.Is(err, io.EOF) {
            return Payload{}, fmt.Errorf("没有可解码的 JSON 值: %w", err)
        }
        // 错误后不把可能部分写入的 out 当成成功结果。
        return Payload{}, fmt.Errorf("字段或输入解码失败: %w", err)
    }
    return out, nil
}

我的偏好是让错误带上所在阶段，但不把整段请求体塞进错误日志。ReadPayload 返回成功只说明解码接受了第一个值，不说明 DisplayName 满足业务必填要求；空字符串检查应当是另一个显式业务判断。

我会先核对可写字段与输入层级

对于普通结构体字段，先看是否导出。小写开头的 displayName 不能仅靠加标签变成普通可写字段；示例使用大写开头的 DisplayName。标签中的 json:"display_name" 指定协议键，json:"-" 则表示忽略字段。

传统 encoding/json 的键匹配接受大小写不敏感匹配，但这不意味着自动做蛇形、驼峰转换。display_name 与 displayName 不应被当成同一个键。我的选择是使用明确标签并发送一致的键，不依赖大小写宽松规则来掩盖协议漂移。

另一个常见偏差是输入为 {"data":{"display_name":"Mira"}}，目标却直接是 Payload。要接收这个结构，就应定义含 Data 字段的外层结构体，再在 Data 内放 Payload；Decoder 不会主动深入每个对象替你寻找同名字段。

把缺失、null和空字符串分开看

新对象里的 string 字段如果未被匹配，仍是空字符串；输入显式传空字符串，也会看到空字符串。传统接口中，null 解到 string 不改变原值，因此在新对象里同样看起来为空。复用旧对象时，缺失字段和 null 对 string 的处理还可能保留上一次值，这也是我在函数内每次声明新对象的原因。

如果业务只需要区分“提供了字符串”与“没有可用字符串”，*string 很方便：新对象中缺失和 null 都表现为 nil，显式空字符串则是非 nil 指针。但它不能单独区分缺失与 null。若这两者业务含义不同，可先读取 map[string]json.RawMessage，通过键是否存在和原始值是否为 null 分别处理，或设计显式存在标志的类型。

此外，omitempty 影响的是编码输出时是否省略字段，不是解码必填约束。添加它不会让缺失键报错；同理，DisallowUnknownFields 拒绝的是未知键，不会要求所有已知字段都出现。

确认传入的是目标地址和未消费的输入

代码里使用 Decode(&out)。传入结构体值而不是可写指针会返回错误，不是一次“悄悄成功”的读取。若在辅助函数中把结构体按值传入，即使对辅助函数里的副本取地址，调用方原对象也不会被修改；这时要改为传指针，或像示例一样返回已解码对象。

Reader 的当前位置同样属于输入条件。若为了打印内容先把流读到末尾，再把同一个 Reader 交给 NewDecoder，通常只能得到 EOF，而不是原始 JSON。排查时可以对一个已知、小型、脱敏的文本样本使用新的 strings.Reader；不要把“记录日志”实现成无意消费业务流。

已有 Decoder 可能预读数据，因此需要连续解码多个值时，应复用同一个 Decoder，不要在同一个底层流上不断重建它。本文的 ReadPayload 只接收第一个值；不要把它放在多值流循环中反复创建 Decoder。

迁移严格策略前保留一组小样本

旧代码默认忽略未知键，启用 DisallowUnknownFields 后，原来容忍的新增键或拼写偏差会变成错误。对内部固定协议，我倾向于显式报错便于发现漂移；对需要前向兼容的外部响应，则可能继续容忍额外字段，同时对关键字段做业务检查。不能不看输入约定就全局开启严格模式。

把下面内容保存为 decode_test.go。这些是读者自测样本，本文未执行。wrong_key 和 nested 在当前严格模式下预期返回错误，不要把这个预期套到默认宽松模式上。

package decodecheck

import (
    "strings"
    "testing"
)

// 把字段映射的预期保留为回归样本，以下用例未在本文执行。
func TestReadPayload(t *testing.T) {
    cases := []struct {
        name, body, wantName string
        wantErr, aliasPresent bool
    }{
        {"mapped", `{"display_name":"Mira","alias":""}`, "Mira", false, true},
        {"missing", `{}`, "", false, false},
        {"null", `{"display_name":null,"alias":null}`, "", false, false},
        {"wrong_key", `{"displayName":"Mira"}`, "", true, false},
        {"nested", `{"data":{"display_name":"Mira"}}`, "", true, false},
        {"type", `{"display_name":7}`, "", true, false},
        {"empty_stream", "", "", true, false},
    }
    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            got, err := ReadPayload(strings.NewReader(tc.body))
            if (err != nil) != tc.wantErr { t.Fatalf("错误状态不符: %v", err) }
            if err != nil { return } // 失败用例不检查部分对象。
            if got.DisplayName != tc.wantName { t.Fatalf("名称不符: %q", got.DisplayName) }
            if (got.Alias != nil) != tc.aliasPresent { t.Fatal("别名存在状态不符") }
        })
    }
}

# 在上述两个文件所在的现有模块包目录执行读者自测。
go test -run '^TestReadPayload$' -count=1 .

JSON字段大写就一定不能读吗？

不能这样判断。传统接口允许大小写不敏感匹配；真正需要核对的是标签后的键名及结构层级，不是只看字母大小写。

增加指针层级就能修复所有空字段吗？

不能。指针解决可写目标或部分空值表达问题，不会修复错误标签、错误层级或已经耗尽的输入。

自定义 UnmarshalJSON 会影响清单吗？

会。若目标类型实现自定义解码方法，应检查方法是否真的写入接收者，以及是否主动忽略了输入字段；普通字段映射规则不能替代自定义方法的行为。

我的结论是先保留错误、再核对映射，最后处理值语义与输入所有权。对于字段为空的排查，这比盲目改标签、换库或加指针更能说明问题究竟发生在哪里。