golang常用库之-protojson 库(json.Marshal 和 protojson.Marshal 序列化对比)

golang常用库之-protojson 库(json.Marshal 和 protojson.Marshal 序列化对比)

什么是protojson 库

protojson 库(google.golang.org/protobuf/encoding/protojson)

protojson 是一个用于处理 Protocol Buffers (protobuf) 和 JSON 之间转换的库,主要应用于 Go 语言中。它由 Google 提供,属于 google.golang.org/protobuf 的一部分。以下是它的主要特点和用途:

  • 功能:
    将 protobuf 消息转换为 JSON 格式(序列化)。
    将 JSON 格式的数据转换回 protobuf 消息(反序列化)。

  • 用途:
    在需要与 JSON 格式交互的场景中(如 API 通信、配置文件解析等),protojson 提供了一种高效的方式来实现 protobuf 与 JSON 的互转。
    支持 protobuf 的扩展特性,如自定义选项和字段映射。

  • 特点:
    高性能:相比标准库 encoding/json,protojson 针对 protobuf 的结构进行了优化。
    灵活性:支持自定义转换规则,例如字段名的映射、忽略空值等。

什么情况需要用 protojson?

仅当以下条件全部满足时:

  • 服务端使用 protobuf 定义数据模型。
  • 通信时通过 JSON 格式传输 protobuf 消息(例如为了兼容性)。
  • 你需要处理 protobuf 特有的特性(如自定义字段名、扩展字段等)。

只有涉及 protobuf 消息时才需要 protojson。

如果你正在处理 Protobuf 消息,强烈建议始终使用 protojson 包进行 JSON 的序列化和反序列化。这样可以确保对 Protobuf 的特定类型(如 WKTs, Any, oneof, enums)的处理是正确和一致的

protoc-gen-go 会将 .proto 文件中的 snake_case (如 max_tokens) 转换为 Go 的 CamelCase (如 MaxTokens)。

最佳实践仍然是坚持只使用 protojson 来处理 Protobuf 消息的 JSON 序列化/反序列化。

json.Marshal 和 protojson.Marshal 序列化对比

标准库的 encoding/json

  • 只认 Go struct 定义的字段和 tag,不理解 Protobuf 的 proto tag。
  • 字段名用 Go 的导出字段名(通常是驼峰),遇到 Protobuf 特有类型(如 *timestamppb.Timestamp、*anypb.Any)只会把它们序列化为结构体,而不是标准的 Protobuf JSON 格式。
  • 不会自动处理 Protobuf 枚举、oneof、默认值、proto3 的空值语义等。

protojson 库(google.golang.org/protobuf/encoding/protojson)

  • 严格遵循 Protobuf 官方 JSON Mapping 规范。
  • 字段名会自动转为 snake_case,与 proto 文件中的字段对齐(除非你设置 UseProtoNames)。
  • 能正确处理 Protobuf 的特殊类型(如 Timestamp、Any、Duration 等),保证序列化结果和其他语言(比如 Java/Python/C++)中的实现一致。
  • 枚举默认导出为字符串而不是数字,和约定一致。
  • 处理空值、默认值、oneof 和未知字段等复杂特性。
  • 支持严格/宽松模式、字段排序、原始字段名、保留未知字段等选项,适用于与 gRPC、APIs 等环境交互。

跨语言与跨平台交互需要遵守 Protobuf 的规范,尤其是和 gRPC-Gateway、Google APIs, Istio, Cloud 原生等生态协作时。protojson 的行为是 Protobuf 官方定义的 JSON 行为,兼容性和正确性才有保证。

序列化器能否用于 Protobuf GO 结构体?输出标准 Protobuf JSON?能正确处理特殊 proto 类型?
encoding/json可以,但有限
protojson.Marshal可以

简单示例

假设你的 proto 结构:

message User {
  string user_name = 1;
  google.protobuf.Timestamp created_at = 2;
}

Go 代码:

body := &pb.User{
    UserName: "tom",
    CreatedAt: timestamppb.Now(),
}

json.Marshal(body) 结果:

{
  "UserName": "tom",
  "CreatedAt": {"seconds": ...,"nanos": ...} // 不是标准的 RFC 3339 字符串
}

protojson.Marshal(body) 结果:

{
  "userName": "tom",
  "createdAt": "2024-05-09T08:00:00Z" // 标准时间格式
}

json.Marshal 的潜在问题 (对于 Protobuf 结构体)

字段名: json.Marshal 会遵循 Go 结构体字段上的 json:“…” 标签。对于 protoc 生成的结构体,这些标签可能直接是 proto 文件的字段名 (如 json:“max_tokens,omitempty”) 或者根据 protoc-gen-go 版本和选项有所不同。这可能导致 JSON 字段名不是标准的 camelCase。

虽然可以用 json.Marshal,但是想要获得符合 Protobuf 规范、兼容所有环境、能正确处理复杂 proto 类型和语义的 JSON,就必须用 protojson。只用标准库可能会导致兼容性、可读性和正确性的问题。

字段名映射:
protojson 默认使用 protobuf 字段的原始名称(如 snake_case),而 encoding/json 默认使用 Go 结构体的字段名(如 CamelCase)。
如果需要自定义 JSON 字段名,可以在 protobuf 文件中通过 json_name 选项指定:

message YourMessage {
    string field_name = 1 [json_name = "customName"];
}

空值处理:
protojson 默认会忽略 protobuf 消息中的空值字段(如 0、“”、nil),而 encoding/json 可以通过 omitempty 控制。
如果需要保留空值,可以使用 protojson.MarshalOptions

jsonData, err := protojson.MarshalOptions{
    EmitUnpopulated: true,
}.Marshal(pbMessage)

protojson 默认忽略空值,encoding/json 依赖 omitempty

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

西京刀客

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值