Go encoding/json/v2 inline 为什么 inline 标签失效（参数形态）

如果把实验阶段的 json:",inline" 直接带到 Go 1.27 的 encoding/json/v2，最先要检查的不是 JSON 输入，而是标签选项本身。Go 1.27 已将这个选项改名为 embed，因此当前写法应是 json:",embed"。

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

排查顺序可以固定为：先把 inline 改成 embed，再确认字段类型是否可嵌入，最后检查字段有没有显式 JSON 名称。三个条件有一个不满足，父对象中的字段就不会按预期展开。

为什么 inline 标签会失效

encoding/json/v2 的字段标签不是把任意字符串都当成兼容别名。Go 1.27 的发布说明明确记录了：实验期间的 inline 选项改名为 embed，并同步调整了行为。因此旧标签不能继续当作当前 v2 的正式写法。

迁移时先做这个最小替换：

type Common struct {
	// 这些字段会作为可嵌入内容参与父对象的 JSON 表示。
	RequestID string `json:"request_id"`
	TraceID   string `json:"trace_id"`
}

type Envelope struct {
	// embed 必须是当前版本支持的独立标签选项。
	Common `json:",embed"`
	// 这个字段仍然属于父对象自身。
	Data string `json:"data"`
}

这里的意图是让 request_id、trace_id 与 data 处在同一个 JSON 对象层级。不要把 inline 与 embed 并列写在同一个标签里，也不要给 embed 再附加 JSON 名称。

字段类型不对时，改名也没有用

embed 不是任意字段的“扁平化开关”。官方文档规定，可嵌入字段应是 Go 结构体、jsontext.Value、字符串键 map，或指向这些类型的未命名指针。字段类型不在这个范围内时，问题就从“标签名错误”变成了“参数形态不符合规则”。

type Extra map[string]any

type Envelope struct {
	// map 的键约束是字符串族，适合承接未被父结构体直接处理的成员。
	Extra `json:",embed"`
	// 指针字段为 nil 时，嵌入内容不会凭空产生。
	*Common `json:",embed"`
}

还要注意，embed 必须是唯一的选项：不能写成 json:",embed,omitempty"，也不能把它写成 json:"common,embed"。如果需要给字段一个普通 JSON 名称，就应去掉 embed，让它成为嵌套对象，而不是继续要求扁平化。

匿名字段和显式名称是两种设计

Go 的匿名结构体字段本身具有隐式嵌入语义，但显式 JSON 名称会改变这层关系。下面两个字段看起来只差一个标签，表达的 JSON 结构却不同：

type Envelope struct {
	// 没有显式 JSON 名称时，按匿名字段参与嵌入规则。
	Common
	// 指定 common 后，它表示一个名为 common 的嵌套成员。
	Named Common `json:"common"`
}

如果目标是得到扁平对象，使用匿名字段或显式的 json:",embed"；如果目标是保留层级，就使用普通名称。不要只看 Go 字段访问语法判断 JSON 结果，必须同时看标签和字段类型。

迁移时按这张清单判断

最后，把这次排查记成一个简单判断：inline 是旧实验写法，embed 才是 Go 1.27 的当前标签；标签正确之后，还要让字段形态和目标 JSON 层级一致。

相关问题

embed 能和 omitempty 一起写吗？

不能。官方文档把 embed 定义为独立选项，不能与其它选项或 JSON 名称组合。

为什么加了 embed 仍然看不到字段？

优先检查嵌入字段是否为 nil 指针、字段是否导出，以及多个字段是否产生了同名 JSON 成员；这些都属于结构体字段解析规则，而不是 inline 的兼容问题。