Go 结构体转 JSON 为什么得到空对象

用 encoding/json.Marshal 把 Go 结构体转成 {}，通常不是 JSON 包坏了，而是结构体对 JSON 编码器“没有可见字段”。最常见的顺序是：字段名小写未导出、标签写成了 json:"-"，或者所有字段都带了 omitempty 且当前值刚好是零值。

先把字段改成大写开头，再检查 json 标签和 omitempty。同时保留 Marshal 返回的错误，不要只盯着打印出来的字节。

第一步：确认字段名是大写开头

Go 的字段可见性由首字母决定。下面的 name 和 age 虽然在同一个包里可以正常赋值，但对 encoding/json 来说它们不是可导出字段，因此编码结果是空对象：

package main

import (
    "encoding/json"
    "fmt"
)

type User struct {
    name string
    age  int
}

func main() {
    b, err := json.Marshal(User{name: "Lin", age: 18})
    if err != nil {
        panic(err)
    }
    fmt.Println(string(b)) // {}
}

修复时只需要把字段改为导出名。JSON 键名是否仍然使用小写，可以交给标签处理：

type User struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

// {"name":"Lin","age":18}

第二步：排查标签是否把字段屏蔽了

标签中的 - 是明确的忽略指令，不是占位符。字段一旦写成 json:"-"，即使它已导出并且有值，也不会出现在结果里。另一个常见坑是把标签名写错，程序不会因为 JSON 键名不是你预期的值而报错。

如果使用匿名嵌入结构体，还要注意同一层级的字段名冲突。多个字段竞争同一个 JSON 名称时，可能全部被忽略；这时给需要保留的字段显式写标签，通常比依赖提升规则更稳。

第三步：确认是不是 omitempty 让字段消失

omitempty 不会让结构体整体失效，它只会逐个省略空字段。但如果结构体里的所有字段都带了这个选项，并且当前值全部为空，最终看起来就会像“空对象”：

type Filter struct {
    Keyword string   `json:"keyword,omitempty"`
    Limit   int      `json:"limit,omitempty"`
    Tags    []string `json:"tags,omitempty"`
}

b, _ := json.Marshal(Filter{})
fmt.Println(string(b)) // {}

这时要先判断业务含义。分页接口可能希望始终传 limit，那就不要给它加 omitempty，或者在构造参数时填入明确默认值。可选筛选条件则适合保留它，让空值不污染请求。

最后用一段最小检查代码定位

排查时不要忽略错误，也不要直接把 []byte 当成结构体打印。保留这段最小代码，可以同时看到类型、错误和 JSON 结果：

func dump(v any) {
    b, err := json.Marshal(v)
    fmt.Printf("type=%T err=%v json=%s\n", v, err, b)
}

dump(User{Name: "Lin", Age: 18})
dump(Filter{})

如果结果是 {} 且没有错误，优先查字段导出、标签和 omitempty；如果有错误，再查函数、通道、循环引用等 JSON 不支持的值类型。把字段一次恢复一个，通常比直接修改业务结构体更快。

相关问题

字段改成大写后，JSON 键名会不会也必须大写？

不会。字段名负责 Go 可见性，json:"name" 可以把输出键名改成小写或其他约定。

结构体字段有值但用了 omitempty，为什么仍然没有输出？

检查它是否仍是空字符串、0、false、nil 指针、空切片或空 map；这些值在默认 v1 语义下都会触发省略。

只打印 json.Marshal 的返回值可以吗？

不建议。返回值有两个，必须检查 error；编码失败时，字节结果不能代替错误处理。

记住排查顺序即可：先看大写开头的字段，再看 json 标签，最后看零值和 omitempty。大多数空对象问题都能在这三步内定位。