Go JSON 字段为空的 struct tag 排查指南

Go 里 JSON 字段为空，先不要急着怀疑 encoding/json 丢数据。这个问题大多落在三个位置：字段没有导出、struct tag 的键名写错，或者 json.Unmarshal 接收的目标不是可写指针。把这三层分开看，通常很快就能定位。

本文只讨论结构体字段、标签和解码目标，不展开自定义 MarshalJSON、嵌套匿名字段或第三方 JSON 库。官方文档入口可以直接查看：https://pkg.go.dev/encoding/json。

先看字段是否能被 encoding/json 访问

默认结构体映射的第一关是字段可访问性。首字母大写的字段是导出字段，encoding/json 可以读取它的值，也可以在解码时把 JSON 值写回去；首字母小写的字段没有导出，不能依靠默认映射参与这两类操作。

package main

import (
    "encoding/json"
    "fmt"
)

type Profile struct {
    Name   string `json:"name"`
    secret string `json:"secret"`
}

func main() {
    value := Profile{Name: "Lin", secret: "hidden"}

    data, err := json.Marshal(value)
    if err != nil {
        // 序列化失败时先处理错误，避免把空输出误判成字段映射问题。
        panic(err)
    }
    fmt.Println(string(data))
}

这个结构体即使给 secret 写了标签，也不会把未导出字段变成可访问字段。标签只负责声明 JSON 名称和选项，不能突破 Go 字段的可见性规则。相反，Name 首字母大写，标签把默认的 Name 映射成了 name。

再核对 struct tag 是否真的指向输入键名

解码时，JSON 对象的键要能和目标结构体字段对应。显式标签应写成反引号包裹的 json:"键名"，最常见的错误包括标签写成了别的键、标签名大小写和输入不一致，或者误写成 json:"-"。

package main

import (
    "encoding/json"
    "fmt"
)

type Order struct {
    OrderID string `json:"order_id"`
    Amount  int    `json:"amount"`
}

func main() {
    input := []byte(`{"order_id":"A-17","amount":299}`)
    var order Order

    if err := json.Unmarshal(input, &order); err != nil {
        // 返回错误能区分类型不匹配，不能只观察结构体的零值。
        panic(err)
    }
    fmt.Printf("%s %d\n", order.OrderID, order.Amount)
}

如果把标签误写成 json:"orderId"，或者把字段写成 json:"-"，OrderID 就可能保持为空。排查时把输入 JSON 的键名和标签逐字对照，尤其注意下划线、连字符、大小写和不可见空格。

没有标签时，标准库会尝试用字段名参与匹配；但依赖这种隐式匹配容易让接口字段改名后变得不直观。对外 JSON 建议明确写出稳定的标签，让代码审查时可以直接看到协议名称。

Unmarshal 时确认目标是可写指针

解码不是把结果“返回”给调用者，而是把数据写入传入的目标。目标应该是指向结构体的指针，例如 &order。如果传入结构体值，调用方给出的只是一个副本，解码无法把更新后的字段带回原变量。

package main

import (
    "encoding/json"
    "fmt"
)

type User struct {
    Nickname string `json:"nickname"`
}

func main() {
    input := []byte(`{"nickname":"gopher"}`)
    var user User

    // 传入 &user，解码器才能把值写入调用方持有的结构体。
    if err := json.Unmarshal(input, &user); err != nil {
        // 语法或类型错误必须先返回，避免继续读取未完成的对象。
        panic(err)
    }
    fmt.Println(user.Nickname)
}

这类问题尤其容易出现在封装函数里：函数参数声明成 func decode(v User) error 时，函数内部拿到的是值副本；若要让调用方得到结果，应改为 func decode(v *User) error，并在调用处传入指针。

func decodeUser(data []byte, target *User) error {
    // target 必须由调用方传入有效地址，结果才会回写到原对象。
    if target == nil {
        return fmt.Errorf("target is nil")
    }
    return json.Unmarshal(data, target)
}

这里的 nil 检查不是标签修复，但能避免把“目标不可写”和“字段映射失败”混成一个问题。收到错误时也不要只打印结构体，先记录 Unmarshal 的返回值。

用最小样例隔离空字段来源

当真实请求经过多层 DTO、转换函数和默认值处理时，可以暂时缩成“固定 JSON + 一个 struct + 一次打印”。这个样例不需要连接数据库，也不要混入 HTTP handler，这样每一项都能对应到一个明确结论。

package main

import (
    "encoding/json"
    "fmt"
)

type Request struct {
    UserID string `json:"user_id"`
    Note   string `json:"note"`
}

func main() {
    raw := []byte(`{"user_id":"u-9","note":"hello"}`)
    var req Request

    // 先检查错误，再观察字段，避免把输入语法错误当成空字段。
    err := json.Unmarshal(raw, &req)
    if err != nil {
        fmt.Println("decode error:", err)
        return
    }
    fmt.Printf("user_id=%q note=%q\n", req.UserID, req.Note)
}

如果最小样例能读到值，问题通常在业务层的字段复制、二次转换或默认值覆盖；如果最小样例仍为空，就按“导出字段 → 标签键名 → 指针目标”的顺序继续检查。这个顺序比盯着最终日志猜原因更快。

一张表记住排查顺序

常见追问

标签写对了，为什么字段还是空？

先确认字段本身是导出的，再确认解码传入了指针；标签只能改变 JSON 名称，不能改变字段可见性，也不能把值写入副本。

字段名一定要和 JSON 键完全一样吗？

显式标签优先决定映射名称。没有标签时可以依靠字段名匹配，但接口协议建议写显式标签，避免字段重命名后产生歧义。

看到零值就代表解码失败吗？

不一定。输入本身可能没有这个键，或者键对应的值就是空字符串、零数值。先检查错误，再确认输入是否包含目标键，最后再判断字段权限与标签。

最快的固定排查方法是什么？

复制一份输入 JSON，保留一个最小结构体，使用 json.Unmarshal(raw, &target)，然后依次核对字段导出状态、标签字面量和目标指针。

总结一下：Go JSON 空字段不要只盯着 struct tag。先看字段能否被访问，再对照标签与输入键名，最后确认 Unmarshal 正在写入正确的指针目标。三层分别确认后，绝大多数问题都能在最小样例中复现并修正。