在Go语言开发中，我们经常会定义一些包含嵌入式结构体（匿名结构体）的类型，用来复用字段或模拟面向对象里的继承关系。当把这些类型通过标准库编码成JSON时，如果不了解底层展开规则，就容易出现字段丢失、多余空值以及不必要的性能损耗。本文从原理到实践，详细说明如何高效完成这类数据的序列化。
一、嵌入式结构体的JSON展开规则
Go的encoding/json包在处理结构体时，会递归检查每个字段。如果某个字段是匿名结构体（即没有显式字段名，只有类型），其内部的导出字段会被提升到外层结构体中，仿佛这些字段直接写在外层一样。这种扁平化展开在多数情况下很方便，但也隐藏了优先级问题。
当外层结构体自身定义了与嵌入式结构体同名的导出字段时，外层字段具有更高优先级，内层同名字段会被完全忽略，而不是合并。这一点和某些语言的继承覆盖不同，Go只是单纯地在反射阶段优先扫描外层字段。理解这一点，才能避免误以为内层数据会补充到JSON中。
package main
import (
"encoding/json"
"fmt"
)
type Base struct {
ID int `json:"id"`
Name string `json:"name"`
}
type User struct {
Base
Name string `json:"name"` // 外层同名，覆盖Base中的Name
Age int `json:"age"`
}
func main() {
u := User{
Base: Base{ID: 1, Name: "base"},
Name: "outer",
Age: 20,
}
b, _ := json.Marshal(u)
fmt.Println(string(b))
// 输出: {"id":1,"name":"outer","age":20}
}
二、减少零值干扰与无用字段
在API响应中，我们往往不希望把未赋值的字段以零值形式输出，例如空字符串、0或者false。标准库提供了omitempty标签选项，但它对嵌入式结构体的处理需要特别注意：只有当整个匿名结构体本身为零值（如所有字段均为零值）时，某些组合写法才会省略，而单个内层字段的omitempty只作用于该字段自身。
如果嵌入式结构体是指针类型，那么当指针为nil时，整个匿名块不会展开任何字段，这比值类型更容易配合omitempty控制输出。在包含可选扩展信息的场景中，使用指针嵌入式结构体可以显著减少报文体积，也降低了序列化时反射遍历的字段数量。
package main
import (
"encoding/json"
"fmt"
)
type Extra struct {
Tag string `json:"tag,omitempty"`
Note string `json:"note,omitempty"`
}
type Product struct {
*Extra `json:"extra,omitempty"`
SKU string `json:"sku"`
}
func main() {
p1 := Product{SKU: "A100"}
b1, _ := json.Marshal(p1)
fmt.Println(string(b1)) // {"sku":"A100"}
p2 := Product{SKU: "A100", Extra: &Extra{Tag: "new"}}
b2, _ := json.Marshal(p2)
fmt.Println(string(b2)) // {"extra":{"tag":"new"},"sku":"A100"}
}
三、自定义MarshalJSON提升控制力
当扁平化展开无法满足业务需求，例如希望把嵌入式结构体放在独立的子对象中，或者需要拼接计算字段，就可以为外层类型实现json.Marshaler接口。通过手动构造map或借助临时结构体，既能保留嵌入关系，又能改变输出形状。
这种方式的缺点是放弃了部分标准库的自动反射便利，但换来了稳定的报文结构和可预期的性能。如果在方法内部复用bytes.Buffer并减少中间map分配，其开销通常低于频繁反射。下面的示例演示了将匿名结构体输出为嵌套子对象而非展开字段。
package main
import (
"bytes"
"encoding/json"
"fmt"
)
type Meta struct {
CreatedAt string `json:"created_at"`
Source string `json:"source"`
}
type Order struct {
Meta
OrderID string `json:"order_id"`
}
func (o Order) MarshalJSON() ([]byte, error) {
var buf bytes.Buffer
buf.WriteString(`{"order_id":`)
id, _ := json.Marshal(o.OrderID)
buf.Write(id)
buf.WriteString(`,"meta":{"created_at":`)
ca, _ := json.Marshal(o.CreatedAt)
buf.Write(ca)
buf.WriteString(`,"source":`)
src, _ := json.Marshal(o.Source)
buf.Write(src)
buf.WriteString(`}}`)
return buf.Bytes(), nil
}
func main() {
o := Order{Meta: Meta{CreatedAt: "2023", Source: "web"}, OrderID: "O1"}
b, _ := json.Marshal(o)
fmt.Println(string(b))
// 输出: {"order_id":"O1","meta":{"created_at":"2023","source":"web"}}
}
四、高频场景下的性能优化
在网关或日志上报这类每秒数万次序列化的场景里，反射带来的分配和CPU消耗会被放大。除了上述结构设计方案，还可以借助sync.Pool缓存缓冲区，避免每次Marshal都申请新内存。另外，如果字段固定，可考虑使用easyjson等代码生成工具，彻底跳过反射。
下面的例子展示了用sync.Pool复用bytes.Buffer来降低分配次数。虽然标准库json.Marshal内部也有缓冲，但自定义出口层再包一层池化，对于组合了自定义MarshalJSON的类型尤其有效。配合指针嵌入式结构体，整体分配字节数可下降明显。
package main
import (
"bytes"
"encoding/json"
"fmt"
"sync"
)
var bufPool = sync.Pool{
New: func() interface{} {
return &bytes.Buffer{}
},
}
type Addr struct {
City string `json:"city"`
}
type Person struct {
Addr
Name string `json:"name"`
}
func fastMarshal(p Person) []byte {
buf := bufPool.Get().(*bytes.Buffer)
buf.Reset()
defer bufPool.Put(buf)
json.NewEncoder(buf).Encode(p)
out := make([]byte, buf.Len())
copy(out, buf.Bytes())
return out
}
func main() {
p := Person{Addr: Addr{City: "bj"}, Name: "tom"}
fmt.Println(string(fastMarshal(p)))
}
五、常见误区与排查建议
不少人在调试时发现嵌入式结构体的字段没有出现在JSON里，第一反应是标签写错，其实多半是同名覆盖或字段未导出。Go只序列化导出字段，匿名结构体里的小写字段同样不会被展开。此外，如果为匿名结构体指定了标签名，如Base json:"base"，它就不再是匿名展开，而会变成嵌套对象。
建议在使用嵌入式结构体做JSON输出前，先写一个小用例打印Marshal结果，确认字段层级符合预期。对于复杂领域模型，优先用组合加显式字段，而非深层匿名嵌套，这样在后期变更接口时不容易引发隐性报文变化。
| 方案 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| 标准匿名展开 | 简单复用字段 | 代码少，自动扁平化 | 同名覆盖，难控层级 |
| 指针匿名嵌入 | 可选扩展信息 | nil时自动省略 | 需判空，稍增间接性 |
| 自定义MarshalJSON | 固定报文结构 | 输出形状完全可控 | 手写编码，易出错 |
| 代码生成工具 | 超高频序列化 | 无反射，性能最佳 | 引入构建依赖 |
综合来看，面对包含嵌入式结构体的JSON序列化，先明确接口契约，再选择扁平展开或嵌套输出，最后在性能瓶颈处引入池化或代码生成，便能在开发效率与运行开销之间取得平衡。