用 google.protobuf.Struct 传动态 JSON 最直接，需 import 并声明为 google.protobuf.Struct payload = 1; Go 中对应 *structpb.Struct，须用 structpb.NewStruct 构造，取值必须通过 getter 方法并检查类型。
proto 里想传动态 JSON，用 google.protobuf.Struct 最直接
它本质是把 JSON 对象序列化成键值对的 Map，支持嵌套、数组、null、数字、字符串、布尔——和 JSON 语义基本对齐。不是“模拟 JSON”，而是官方定义的通用结构化数据类型。
实操建议：
- 在
.proto文件中必须先import "google/protobuf/struct.proto"; - 字段声明写成
google.protobuf.Struct payload = 1;，别手滑写成Struct（缺包名）或struct（小写，编译直接报错） - 生成 Go 代码后，对应字段类型是
*structpb.Struct，不是map[string]interface{}，也不能直接 json.Unmarshal 到它身上
Go 侧怎么把 map 或 JSON 字符串转成 structpb.Struct
不能手动 new 然后塞字段——structpb.Struct 的内部字段是只读的，必须用构造函数。
常见错误现象：直接赋值 s.Fields["key"] = … 编译失败；或用 json.Unmarshal 解到空 struct 上，结果字段全 nil。
立即学习“go语言免费学习笔记（深入）”；
正确做法：
- 从
map[string]interface{}转：用structpb.NewStruct，例如structpb.NewStruct(map[string]interface{}{"name": "foo", "tags": []string{"a", "b"}}) - 从 JSON 字符串转：先
json.Unmarshal到map[string]interface{}，再喂给structpb.NewStruct；别试图用jsonpb（已弃用）或protojson.Unmarshal直接解到*structpb.Struct——它不支持 - 注意：float64 在 JSON 中可能被误读为 int，
structpb会按 JSON 原始类型存，但 Go 里取值时得用GetNumberValue()或GetStringValue()显式判断类型
反向：从 structpb.Struct 提取数据时容易掉坑
它不像普通 map 那样能直接下标取值，所有访问都得走 getter 方法，而且类型必须匹配，否则 panic 或返回零值。
使用场景：比如你收到一个 RPC 请求，payload 是 google.protobuf.Struct，要取 user.id 和 user.profile.avatar。
实操要点：
- 取顶层字段用
s.GetFields()["key"]，返回*structpb.Value，再调.GetStringValue()/.GetNumberValue()等 - 嵌套对象要一层层剥：
s.GetFields()["user"].GetStructValue().GetFields()["profile"].GetStructValue().GetFields()["avatar"].GetStringValue() - 数组？用
.GetListValue()，然后遍历.GetValues()，每个仍是*structpb.Value - 没字段或类型不对时，getter 返回零值（比如
GetStringValue()返回空字符串），不会报错——容易静默丢数据，务必先用.GetKind()检查类型
性能和兼容性要注意这几点
structpb.Struct 底层是 proto message，序列化后比原生 JSON 多一倍体积，尤其嵌套深时；跨语言调用没问题，但 JS/Python 客户端拿到的是标准 JSON-like 结构，Go 这边却得写一堆 getter。
参数差异和取舍：
- 如果只是偶尔传几个可选字段，用
oneof+ 若干optional字段更轻量、类型安全 - 如果真需要任意结构（比如 webhook 配置、低代码表单 schema），
Struct合理，但建议加个 wrapper message 包一层，字段名别叫data或payload，写清楚业务含义，比如custom_config - 别在高频路径上反复
NewStruct→Marshal→Unmarshal→ 取值，开销不小；可以缓存解析后的 map，或提前约定好固定 key，用专用 struct 替代
最常被忽略的是类型检查——structpb.Value 的 kind 字段决定了你该调哪个 getter，漏判就拿不到值，还不好 debug。
