不能直接用标准库json，因为其不理解Protobuf的编码语义：字段名驼峰转换、omitempty行为差异、nil切片/未设字段反序列化为零值、Timestamp等Well-Known Types无法正确处理，且忽略proto tag中的协议特定逻辑。
Go 中 Protobuf 与 JSON 互转不能直接用 json.Marshal / json.Unmarshal，必须通过官方 google.golang.org/protobuf/encoding/protojson 包——否则字段名、空值、嵌套结构全乱。
为什么不能直接用标准库 json？
Protobuf 的 Go 结构体是带 tag 的导出字段（如 json:"name,omitempty"），但这些 tag 是生成器写死的，且只适配 proto2 的旧规则；proto3 默认忽略 omitempty，还强制把下划线转驼峰（user_name → userName），而标准库 json 不识别 proto 的编码语义。更关键的是：nil 切片、nil map、未设置的可选字段，在标准 json 反序列化后可能变成零值而非 nil，破坏业务判断逻辑。
常见错误现象：
- 反序列化 JSON 后
proto.Message.ProtoReflect().IsValid()返回 false -
repeated字段在 JSON 中为null，但 Go struct 对应切片变成空切片（非 nil），导致后续len()==0无法区分“没传”和“传了空数组” - 时间字段（
google.protobuf.Timestamp）变成字符串后，用json.Unmarshal会报错或静默失败
protojson.MarshalOptions 的关键配置项
默认行为对大多数场景不友好：比如不保留未知字段、把零值字段也输出、不兼容 camelCase。实际使用时至少要改三项：
-
Indent: " "—— 开启格式化，调试时必须加 -
EmitUnpopulated: false—— 关闭零值输出（proto3 默认 true，会导致"enabled": false即使你根本没设过该字段） -
UseProtoNames: true—— 用原始字段名（如user_id），而不是转成userId；和前端约定用下划线时必开 - 额外建议：
AllowPartial: true—— 允许缺失 required 字段（proto3 已废弃 required，但老协议还有）
示例：
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
marshaler := &protojson.MarshalOptions{
Indent: " ",
EmitUnpopulated: false,
UseProtoNames: true,
}
data, _ := marshaler.Marshal(msg)
protojson.UnmarshalOptions 的坑点
反序列化比序列化更容易出错，尤其当 JSON 来自外部系统（比如前端或第三方 API）：
-
DiscardUnknown: false—— 默认 true，遇到 proto 里没有的字段就丢弃；调试时建议设 false 并配合protojson.UnmarshalOptions.ReportUnknownFields捕获问题 -
AllowPartial: true—— 必须开，否则 JSON 少一个字段就整个失败（proto3 没有 required，但很多业务逻辑仍依赖字段存在） - 时间/枚举/bytes 字段需特别注意：
google.protobuf.Timestamp输入必须是 RFC3339 字符串（如"2024-01-01T00:00:00Z"），不是毫秒数；枚举值接受字符串名（"PENDING"）或数字，但默认只认字符串名；bytes字段默认按 base64 解码，不能传 hex 或明文
示例（带错误检查）：
unmarshaler := &protojson.UnmarshalOptions{
DiscardUnknown: false,
AllowPartial: true,
}
err := unmarshaler.Unmarshal(bytes, msg)
if err != nil {
// 注意：err 可能是 *protojson.ParseError，可 .Field() 拿到具体字段名
}
如何处理 proto2 和 proto3 混合场景？
老服务用 proto2、新模块用 proto3 时，JSON 行为差异极大：proto2 默认输出所有字段（含零值），proto3 默认不输出未设置字段；proto2 的 optional 字段在 JSON 里是 "field": null，proto3 的同名字段却是完全不出现。如果必须共存：
- 统一用
UseProtoNames: true+EmitUnpopulated: false，让两边都“不输出未设字段” - 避免在 proto2 中用
optional字段传null，改用oneof显式表达“未设置”语义 - 对 timestamp/duration 等 Well-Known Types，确保所有端都用 RFC3339 格式，别混用毫秒数
真正麻烦的是嵌套消息中部分字段是 proto2、部分是 proto3 —— 这时只能靠中间层做字段级转换，没有银弹。
