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