Go encoding/json 字段标签冲突时的解析选择

我在给一组历史结构体补 JSON 接口时，遇到过一种很容易误判的现象：输入里明明有 name，json.Unmarshal 返回的错误也是 nil，但目标结构体里的字段却保持零值。问题通常不在 JSON 文本，而在嵌入结构体把多个同名字段带到了同一层级。

官方地址：https://pkg.go.dev/encoding/json

encoding/json 对嵌入字段会按层级和标签筛选候选：同一层级如果有 JSON 标签，未标记字段会先被排除；只剩一个候选时使用它；如果仍有多个同优先级候选，则全部忽略，而且不一定返回错误。

一、先用最小结构体复现“没有报错但没赋值”

先把两个嵌入结构体都定义一个 Name 字段。它们没有 JSON 标签，经过提升后会在外层形成两个同名候选。

package main

import (
	"encoding/json"
	"fmt"
)

type AuditInfo struct {
	Name string
}

type ProfileInfo struct {
	Name string
}

type Envelope struct {
	AuditInfo
	ProfileInfo
}

func main() {
	var value Envelope
	err := json.Unmarshal([]byte(`{"name":"alice"}`), &value)
	// 解码错误为 nil 只说明 JSON 语法和类型转换没有失败。
	fmt.Printf("err=%v audit=%q profile=%q\n", err, value.AuditInfo.Name, value.ProfileInfo.Name)
}

这个例子里两个字段的嵌入层级相同、名称相同、也都没有标签。encoding/json 无法在它们之间做出唯一选择，于是两个字段都不会接收 name。这类情况的危险点是：它是一个静默的字段选择结果，而不是显眼的语法错误。

二、字段层级比字段声明位置更关键

判断冲突时不要只看字段分别写在哪个类型里，要看它们被提升到外层后的嵌入层级。直接声明在外层的字段通常比嵌入字段更浅；如果最浅层已经有唯一同名字段，深层的同名字段不会参与竞争。

可以先按三个问题排查：

1. 同名字段是否都能被 JSON 看到，也就是字段是否导出、是否被 json:"-" 排除？
2. 候选字段是否处于同一个最浅嵌入层级？
3. 同一层级中是否至少有一个字段写了 JSON 标签？

这些问题比“JSON 里有没有这个 key”更接近真正原因。尤其是在长期演进的结构体中，新嵌入类型可能让原本唯一的候选突然变成两个。

三、同层级出现标签时，未标记字段先退出竞争

下面把其中一个 Name 明确标成 json:"name"，另一个仍然使用默认字段名。两者名称看起来一样，但标签参与了候选筛选。

package main

import (
	"encoding/json"
	"fmt"
)

type LegacyProfile struct {
	Name string
}

type CurrentProfile struct {
	Name string `json:"name"`
}

type TaggedEnvelope struct {
	LegacyProfile
	CurrentProfile
}

func main() {
	var value TaggedEnvelope
	err := json.Unmarshal([]byte(`{"name":"alice"}`), &value)
	// 同层级只有带标签的字段保留下来，读取结果应来自 CurrentProfile。
	fmt.Printf("err=%v legacy=%q current=%q\n", err, value.LegacyProfile.Name, value.CurrentProfile.Name)
}

这里的标签不是“把两个字段合并成一个”，而是帮助 JSON 字段选择规则缩小候选集合。实际接口里，如果一个字段代表旧协议、另一个字段代表新协议，最好直接改成不同的 JSON 名称，避免把“标签优先级”当成隐藏的兼容策略。

四、两个同名标签仍然会被一起忽略

最容易被误解的变体是：两个字段都写了完全相同的标签。标签确实让它们进入了 JSON 候选集合，但并没有替开发者决定使用哪一个；当它们仍处于同层级、同优先级时，选择依旧不唯一。

package main

import (
	"encoding/json"
	"fmt"
)

type Billing struct {
	Name string `json:"name"`
}

type Shipping struct {
	Name string `json:"name"`
}

type OrderView struct {
	Billing
	Shipping
}

func main() {
	var value OrderView
	err := json.Unmarshal([]byte(`{"name":"alice"}`), &value)
	// 两个候选同层同标签，错误仍可能为 nil，但两个字段都保持空字符串。
	fmt.Printf("err=%v billing=%q shipping=%q\n", err, value.Billing.Name, value.Shipping.Name)
}

因此，看到“加了标签还是空值”时，不要只确认标签拼写，还要数一数同层级是否仍然有多个相同标签。这个检查也适用于 Marshal：字段选择不唯一时，输出中同名字段同样可能不按直觉出现。

五、把修复动作分成“消除歧义”和“保留兼容”

如果结构体确实需要同时保留两个业务字段，最稳妥的做法是给它们分配不同的 JSON 名称，而不是依赖谁恰好带标签。

type OrderView struct {
	BillingName  string `json:"billing_name"`
	ShippingName string `json:"shipping_name"`
}

// 明确的 JSON 名称把两个业务语义拆开，避免同名候选再次竞争。
func decodeOrder(data []byte) (OrderView, error) {
	var value OrderView
	if err := json.Unmarshal(data, &value); err != nil {
		return OrderView{}, err
	}
	return value, nil
}

如果外部协议只能提供一个 name，则不要把两个业务对象都直接嵌入到同一个接收结构体里。可以增加一个专门的传输层结构体，先接收唯一的 name，再由业务代码根据上下文分配到 Billing 或 Shipping。这样兼容规则写在显式代码里，后续维护者也能看见。

六、排查时不要把 nil 错误当成字段一定成功

json.Unmarshal 的错误主要反映 JSON 语法、类型不匹配和自定义解码过程等问题。字段候选发生歧义时，标准库可能直接忽略相关字段，所以排查要同时检查错误和结果。

func decodeAndReport(data []byte) error {
	var value OrderView
	if err := json.Unmarshal(data, &value); err != nil {
		return err
	}
	// 解码没有报错后仍要检查关键字段，避免把静默忽略当成成功赋值。
	if value.BillingName == "" || value.ShippingName == "" {
		return fmt.Errorf("关键字段为空")
	}
	return nil
}

在真实项目中，空字符串未必都是错误，因此这里的检查应替换成业务上可靠的必填判断，例如指针、额外的存在标记或请求级校验。重点是把“JSON 能否解析”和“目标字段是否按预期被选择”分成两个判断。

七、三种冲突场景速查

八、总结

Go encoding/json 的字段标签不是简单的别名表，它还参与嵌入字段的候选筛选。处理同名字段时，先看最浅嵌入层级，再看这一层有没有标签；筛选后只剩一个候选才会稳定赋值，多个同优先级候选则可能静默忽略。工程上最可靠的策略是让 JSON 名称表达唯一业务语义，必要时使用专门的传输结构体，并在解码后检查关键结果。

相关问题

• 为什么 json.Unmarshal 返回 nil，结构体字段仍然是零值？
• 两个嵌入结构体字段名相同但标签不同，哪个字段会接收数据？
• 如何用 json:"-" 明确排除一个嵌入字段？
• 什么时候应该放弃匿名嵌入，改用显式的请求 DTO？