被网文带偏的 Go 坑：`json:",inline"` 到底能不能展平结构体？

闻溪

发布时间：2026-08-25 | 76人浏览过

原创

前言

在 Go 项目里，`json:",inline"` 经常被当成一种“标准写法”到处复制，真正跑起来却发现 JSON 根本没按预期展平。问题不在语法难，而在不少教程把 YAML、BSON 甚至第三方库的规则混进了 `encoding/json`；本文用可复现示例和标准库行为，把误区、正确写法和 Review 检查点一次讲清。

在 Go 项目里，`json:",inline"` 是个很典型的“看起来合理、实际没效果”的坑：不少人是在别的文章里照着抄，直到序列化结果不对，才发现标准库根本不认这个写法。下面就把这件事拆开讲清楚：先看它为什么会失灵，再看 `encoding/json` 真正支持的展平方式，最后补上这类误解最常见的来源和团队里可执行的排查办法。

为什么 `json:",inline"` 在标准库里不会生效

很多网文会直接给出这样的说法：只要给结构体字段加上 json:",inline"，子结构体就会自动展平到外层 JSON。问题在于，这套说法并不适用于 Go 官方标准库 encoding/json。

对比标准库忽略 json inline 与实际嵌套输出的暖色专栏配图 — **`json:",inline"` 为什么看起**把 `json:",inline"` 写进标准库场景时，代码能运行，但输出仍是嵌套结构。

先看一个很常见的误用示例：

type BaseInfo struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

// 错误示范：听信网文误加了 ,inline
type UserBad struct {
    Info BaseInfo `json:",inline"`
    Role string   `json:"role"`
}

如果按不少教程的说法，开发者通常期待拿到下面这样的结果：

{"id":1002,"name":"Bob","role":"User"}

但标准库并不是这么解析 tag 的。对 encoding/json 来说，结构体 tag 里第一个逗号前面的内容是字段名，逗号后面才是选项，比如 omitempty。

因此，json:",inline" 的实际含义是：字段名留空，于是默认使用结构体字段名 Info；逗号后面跟了一个叫 inline 的选项，但标准库并不认识它。

这里最容易误导人的地方在于，encoding/json 对未知选项不会报错，而是直接静默忽略。也就是说，代码能正常编译运行，只是输出结果不会按你想的那样展平，最终仍然是普通嵌套结构：

{"Info":{"id":1002,"name":"Bob"},"role":"User"}

还有一种更隐蔽的写法是少写了逗号，直接写成 json:"inline"。这种情况甚至不是“无效选项”，而是把 inline 当成了字段名，最终生成的 JSON key 会直接变成 "inline"。这类问题在 Review 时尤其值得留意，因为代码表面上并没有语法错误。

标准库里展平结构体的正确做法

如果目标就是把公共字段展开到外层 JSON，Go 标准库其实早就提供了明确且稳定的方案：匿名结构体嵌入。它依赖的是 Go 语言本身的嵌入机制，不需要额外发明任何 JSON tag。

Go 标准库匿名嵌入展平结构体的正确做法暖色专栏配图 — **标准库展平结构体，关键在匿名嵌入**标准库真正支持的展平方式不是加 tag，而是使用匿名结构体嵌入。

正确写法如下：

type BaseInfo struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

// 官方标准库正确姿势：匿名嵌入 BaseInfo
type UserStandard struct {
    BaseInfo        // 匿名嵌入，无需任何额外 tag
    Role     string `json:"role"`
}

这种写法下，encoding/json 会把匿名嵌入结构体里的字段视为外层字段的一部分，序列化结果才会是预期中的展平形式：

{"id":1001,"name":"Alice","role":"Admin"}

这里的关键不是 tag，而是“匿名”两个字。只要给 BaseInfo 起了字段名，比如写成 Info BaseInfo，它就重新变成了普通嵌套字段。

还有一个容易踩的反向坑：即便用了匿名嵌入，如果又顺手给它补了普通 tag，例如显式指定键名，那么标准库会把它理解成一个需要单独输出的字段，结果也会重新退回嵌套结构。换句话说，在标准库里想要展平，最稳妥的写法往往恰恰是“少写点”。

这个误解为什么会在网上越传越广

`json:",inline"` 之所以流传得像真有其事，不是因为标准库文档写得含糊，而是因为 Go 生态里不同序列化库对“展平”这件事的设计本来就不一样，很多文章在搬运示例时把语法场景混在了一起。

不同序列化库 inline 语法差异与代码审查要点的暖色专栏配图 — **别把别的库语法带进标准库 JSON**很多误导来自不同库语法混用，Review 时最好把标准库、YAML、BSON 和第三方库分开看。

常见库的做法大致如下：

常见序列化库展平语法对比：
├── encoding/json (标准库)  --> 匿名结构体嵌入（无需任何 tag）
├── yaml.v3 (YAML 库)       --> 必须显式写 `yaml:",inline"`
├── mongo-driver (BSON 库)   --> 必须显式写 `bson:",inline"`
└── jsoniter (第三方 JSON 库) --> 扩展支持 `json:",inline"`

问题通常就出在这里。很多人先接触的是 Kubernetes 配置、YAML 解析或 MongoDB 驱动，看到 yaml:",inline"、bson:",inline" 这些写法后，再把它们直接套到标准库 JSON 上。还有一些文章使用的是第三方库 jsoniter，它本身确实提供了扩展能力，但示例里没有把“这不是标准库行为”说清楚，读者就很容易误判。

当这些内容继续被二次转载、摘抄和拼接后，搜索结果里就会出现大量看起来互相印证、实则来源相同的错误说法，最后把一个并不存在于标准库中的 tag 传成“默认技巧”。

顺带一提，围绕 encoding/json/v2 的讨论里，社区确实提到过引入真正的 inline 标记，用于诸如把 map[string]any 作为未匹配键兜底容器的场景。但这属于未来版本设计讨论，至少在当前广泛使用的标准库 v1 中，json:",inline" 依然没有官方语义。