JSON 字段有值却解码为零值的排查清单

Go 里最容易误判的一类 JSON 问题是：原始数据明明有值，解码后结构体字段却还是零值。先不要急着改业务逻辑。通常要沿着“键名匹配—字段可写—输入语义—类型错误”四层排查：字段名或标签不匹配时，标准库默认可能安静地忽略；类型不兼容时要看返回的 UnmarshalTypeError；输入是 null 时，指针、切片、map 和 interface 还可能被置为 nil。

这份清单只针对标准库 encoding/json 解码到 Go 结构体的场景。排查时先保留原始 JSON，再同时打印错误和目标对象，不要只看最后一个字段值。

先确认 JSON 键和 Go 字段怎么匹配

结构体字段必须是导出的，或者通过 json 标签明确指定名称。下面的 user_name 能写入 UserName，而小写字段 hidden 不会成为可写的 JSON 目标。omitempty 只影响编码时是否省略空值，不会让解码阶段“强行写入”。

package main

import (
    "encoding/json"
    "fmt"
)

type Profile struct {
    UserName string `json:"user_name"` // 标签把外部键映射到导出字段
    Age      int    `json:"age"`       // 导出字段才能接收解码结果
    hidden   string `json:"hidden"`    // 小写字段不可由 encoding/json 写入
}

func main() {
    input := []byte(`{"user_name":"Lin","age":28,"hidden":"x"}`)
    var profile Profile

    err := json.Unmarshal(input, &profile) // 必须传目标指针，让解码器写回对象
    if err != nil {
        fmt.Println("decode error:", err) // 先保留错误，不要只打印 profile
        return
    }
    fmt.Printf("name=%q age=%d hidden=%q\n", profile.UserName, profile.Age, profile.hidden)
}

这里最常见的误区有三个：把 JSON 的下划线键写成了另一个标签名；把字段首字母写成小写；把 json:"-" 当成普通标签。标准库对没有对应结构体字段的对象成员默认忽略，因此字段拼错时不一定立刻报错。

把错误返回值当作定位线索

如果键名能匹配，下一层就是输入值和目标类型是否兼容。例如 JSON 字符串不能直接写进 int，过大的数字也可能溢出。Unmarshal 会尽量继续处理，并返回最早遇到的 UnmarshalTypeError；忽略这个错误再读取结构体，很容易把“部分写入”误认为“字段没有解码”。

package main

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

func decodeCount(input []byte) error {
    var payload struct {
        Count int `json:"count"` // 这里要求 JSON number 能落进 int
    }
    err := json.Unmarshal(input, &payload)
    if err == nil {
        return nil
    }

    var typeErr *json.UnmarshalTypeError
    if errors.As(err, &typeErr) { // 类型错误携带字段和目标类型线索
        return fmt.Errorf("field=%s want=%s: %w", typeErr.Field, typeErr.Type, err)
    }
    return err // 语法错误等其他问题也要继续向上返回
}

如果你希望多余字段也尽早暴露，可以使用 Decoder.DisallowUnknownFields。它适合接口契约较稳定的入口；对需要兼容上游新增字段的场景，则要保留默认行为，并在业务层记录原始输入。

decoder := json.NewDecoder(bytes.NewReader(input))
decoder.DisallowUnknownFields() // 把拼写错误或多余键变成显式错误
if err := decoder.Decode(&profile); err != nil {
    fmt.Println("strict decode error:", err) // 先修正键名、标签或契约版本
    return
}

区分零值、null 和缺失字段

Go 的零值不等于“解码失败”。字符串的零值是空字符串，整数是 0，布尔值是 false；如果 JSON 本来就是这些值，结果完全正常。对于指针、切片、map 和 interface，JSON null 会把目标设为 nil，而对象里缺少这个键时，已有值通常不会被覆盖。

因此需要表达“没有提供”和“明确提供 0”时，优先使用指针或带存在性信息的类型，而不是只比较零值：

type Update struct {
    Limit *int `json:"limit"` // nil 表示未提供或收到 null，非 nil 才表示明确给值
}

func readLimit(input []byte) {
    var update Update
    if err := json.Unmarshal(input, &update); err != nil {
        fmt.Println("decode error:", err) // 输入格式错误仍要单独处理
        return
    }
    if update.Limit == nil {
        fmt.Println("limit is absent or null") // 不能把它等同于 0
        return
    }
    fmt.Println("limit:", *update.Limit)
}

用最小探针缩小问题范围

当完整结构体很大时，先把原始对象解到 map[string]json.RawMessage，确认字段是否真的存在，再单独解目标字段。这一步不替代正式模型，而是把“上游没有发”“键名不对”和“目标类型不对”分开。

func inspectField(input []byte, key string) error {
    var raw map[string]json.RawMessage
    if err := json.Unmarshal(input, &raw); err != nil {
        return fmt.Errorf("read object: %w", err) // 先确认外层 JSON 本身可解析
    }

    value, ok := raw[key]
    if !ok {
        return fmt.Errorf("missing JSON key %q", key) // 键不存在，不是目标字段丢值
    }
    fmt.Printf("raw %s = %s\n", key, value) // 保留字段原文，便于判断 null 或类型
    return nil
}

最后按这个顺序复查：一是确认传入的是目标指针；二是核对 JSON 键和 json 标签；三是检查字段导出性与 json:"-"；四是打印并判断错误类型；五是区分缺失、null 和合法零值；六是检查是否存在自定义 UnmarshalJSON 改写了赋值逻辑。这样通常不需要盲目替换结构体或重复请求上游。

常见追问

JSON 键大小写不同一定解码失败吗？

标准库 v1 的结构体解码会优先精确匹配，也接受大小写不敏感匹配；但显式标签、嵌入字段冲突和自定义解码逻辑可能改变结果，生产接口仍建议把标签写清楚。

未知字段为什么没有报错？

这是 encoding/json 的默认行为。需要契约严格时使用 Decoder.DisallowUnknownFields；需要向前兼容时保留默认行为，并记录原始输入或版本信息。

为什么打印出来是 0，但没有 error？

先判断输入是否缺少字段、值是否为合法的 0、是否为 null，以及目标字段是否为指针。只有在这些情况都排除后，才继续检查自定义解码方法或嵌入字段冲突。