如何自定义 Go 结构体字段的默认 JSON/BSON 字段名映射规则

如何自定义 Go 结构体字段的默认 JSON/BSON 字段名映射规则

Go 语言中结构体字段的 JSON 和 BSON 序列化，默认遵循一套从 PascalCase 到 snake_case 或原样保留的策略。但问题是，这套默认行为无法全局修改。想要实现统一的驼峰命名约定，要么老老实实在每个字段后显式声明标签，要么就得借助一些代码生成工具来达成“零重复标签”的优雅目标。

在 Go 语言里，结构体字段上的 `json` 和 `bson` 标签，直接决定了它在序列化（比如调用 `json.Marshal` 或 `bson.Marshal`）时对外展示的键名。先来看看默认行为是怎么一回事：

• encoding/json 包：它的策略是保持首字母大写不变。比如字段 `JdId` 序列化后会变成 `"JdId"`。当然，如果字段名是小写字母开头，它会被直接忽略，不参与序列化。
• go.mongodb.org/mongo-driver/bson 包：它的默认行为则不同，会将字段名转为全小写、并且单词间无分隔符的 snake_case 形式。所以 `JdId` 到了 BSON 里，就变成了 `"jdid"`。

这显然和很多开发者的期望不符。大家通常希望的是统一使用 lowerCamelCase（也就是小写开头的驼峰命名），比如 `JdId` 变成 `"jdId"`，`AcceptTimestamp` 变成 `"acceptTimestamp"`。更重要的是，没人愿意在拥有几十上百个字段的大型结构体里，为每个字段重复书写逻辑相同的标签——这不仅是体力活，更是维护的噩梦。

那么，有没有一个一劳永逸的全局配置呢？很遗憾，答案是否定的。无论是 Go 语言的标准库 encoding/json，还是主流的 MongoDB 驱动 go.mongodb.org/mongo-driver/bson，都不支持全局自定义字段名的转换规则。 它们的逻辑非常明确：标签优先。如果字段有标签，就严格使用标签里写的名字；如果没有标签，就套用内部那套不可配置的默认推导逻辑。

✅ 标准解决方案：显式声明标签

所以，最直接、最正确的做法，就是为每个需要序列化的导出字段，显式地加上标签，并确保团队遵循统一的命名约定。就像下面这样：

type CvJdRelationInfo struct {
    JdId            string `json:"jdId" bson:"jdId"`
    CvId            string `json:"cvId" bson:"cvId"`
    Status          int16  `json:"status" bson:"status"`
    AcceptTimestamp int64  `json:"acceptTimestamp" bson:"acceptTimestamp"`
}

这样一来，无论用哪个包进行序列化，输出的键名都会是规整的小写驼峰格式。

⚠️ 需要留意的几个细节

• 拼写一致性：在写 bson 标签时，要特别注意拼写。比如 `acceptTimestamp` 里的 “Timestamp” 要写全，确保和字段名以及你的业务期望完全一致。建议统一采用标准的 camelCase 拼写。
• 驱动版本差异：如果你还在使用较老的、已归档的 `gopkg.in/mgo.v2` 驱动，需要注意它的 bson 默认行为可能略有不同（比如会自动添加下划线转换）。务必确认清楚你所用的驱动版本和其具体行为。
• 避免大小写陷阱：一个常见的错误示例是写成 `json:"Status"`。这会导致 JSON 输出键名为 `"Status"`（首字母大写），这通常不符合主流 REST API 的命名惯例，应当避免。像 `json:"status"` 配合 `bson:"status"` 这样的写法才是安全且符合惯例的。

? 进阶方案：用工具解放双手

如果实在厌倦了手动编写重复的标签，有没有更“懒”的办法？有的，那就是借助代码生成工具。思路可以借鉴 `stringer` 工具，或者编写自定义的 `go:generate` 脚本。

具体来说，你可以通过分析代码的抽象语法树（AST），自动将结构体字段名（如 `JdId`）映射为目标键名（如 `"jdId"`），然后自动生成带有规范标签的代码。社区里已经有了一些现成的工具可以参考，比如 github.com/freddierice/structtag，或者你也可以根据自己的需求，编写一个轻量的 AST 分析器来实现。

? 核心总结

归根结底，Go 语言在序列化标签机制的设计哲学上，始终坚持“显式优于隐式”的原则。因此，“省略标签”这只在默认规则恰好满足你需求的极少数场景下才可行。

一旦你需要的是像 lowerCamelCase 这样特定的命名风格，那么最健壮、可移植性最强、且不依赖任何特殊运行时逻辑的方式，就是为每个导出字段添加上标准化的 `json` 和 `bson` 标签。这不仅是 Go 社区的事实标准，也被 Swagger/OpenAPI、Gin、Echo 等大量主流框架和工具链所广泛兼容和支持。