序列化【免费下载链接】protobuf[Deprecated] Protocol Buffers for Go with Gadgets项目地址https://gitcode.com/gh_mirrors/proto/protobuf点击查看免费下载gogoprotobuf本仓库项目名 protobuf全称 Protocol Buffers for Go with Gadgets在标准 goprotobuf 之上通过一组以(gogoproto.xxx)形式书写在.proto文件中的自定义扩展extensions驱动代码生成插件为消息生成更快的 Marshal/Unmarshal、更符合 Go 习惯的结构以及丰富的辅助方法。本文以仓库根目录 extensions.md 为核心结合 gogoproto/gogo.proto 的扩展定义、test/example/example.proto 的综合示例与各插件源码系统梳理全部扩展项的用途、默认值与使用要点帮助你快速上手并在自己的项目中精准选用。扩展机制是怎么工作的所有 gogoprotobuf 扩展都定义在 gogoproto/gogo.proto 中它们通过extend挂载到 Protocol Buffers 官方的各类 Options 上google.protobuf.FileOptions文件级选项例如goproto_getters_all 63001、marshaler_all 63017google.protobuf.MessageOptions消息级选项例如marshaler 64017、goproto_getters 64001google.protobuf.FieldOptions字段级选项例如nullable 65001、customtype 65003、jsontag 65005google.protobuf.EnumOptions/EnumValueOptions枚举级选项例如enum_customname 62023、enumvalue_customname 66001。代码生成时protoc-gen-gogo/main.go 作为 protoc 插件运行vanity/command/command.go 中通过匿名导入注册了compare、equal、marshalto、unmarshal、size、stringer、union、face、populate、gostring、description、enumstringer、testgen等所有插件再调用GenerateAllFiles()一次性产出全部生成代码。也就是说你只需要在.proto里声明扩展选项protoc --gogo_out.就会自动把对应插件的代码写进生成的.pb.go。判断某个选项是否生效的逻辑集中在 gogoproto/helper.go例如IsMarshaler会先读消息级E_Marshaler未设置时回退到文件级E_MarshalerAll最终默认值为false——这正是消息级选项可以覆盖文件级选项这一规则的源码实现。快速编解码生成 Marshal、Unmarshal 与 Size 方法标准 goprotobuf 在编解码时依赖反射reflect。gogoprotobuf 可以为每个消息生成手写的Marshal、MarshalTo、Size或ProtoSize与Unmarshal方法从而大幅提升序列化性能。仓库 bench.md 记录了 2013 年 6 月在某 Intel Core i7 上对比反射实现与生成代码的基准数据Marshal 普遍提速约 1.6x5.4x例如BenchmarkNidOptCustomProtoMarshal从 1209 ns/op 降到 310 ns/opUnmarshal 提速约 1.1x10.4xBenchmarkNidOptEnumProtoUnmarshal从 762 ns/op 降到 73 ns/op。该板块涉及的全部扩展项如下名称作用范围类型说明默认值marshalerMessagebool为指定消息生成Marshal与MarshalTo方法falsesizerMessagebool为指定消息生成Size方法falseunmarshalerMessagebool为指定消息生成Unmarshal方法falseprotosizerMessagebool为指定消息生成ProtoSize方法falseunsafe_marshaler已废弃Messagebool若为 true生成Marshal与MarshalTo方法生成的代码会使用 unsafe 包falseunsafe_unmarshaler已废弃Messagebool若为 true生成Unmarshal方法使用 unsafe 包falsestable_marshalerMessagebool与 marshaler 类似但保证输出确定性代价是损失部分速度falsetypedeclbetaMessagebool若为 false生成的输出中不包含该消息的类型声明要求同时启用 marshaler 与 unmarshalertrue生成代码长什么样以 test/example/example.proto 中的消息 B 为例文件头部声明了option (gogoproto.marshaler_all) true;等message B { option (gogoproto.description) true; optional A A 1 [(gogoproto.nullable) false, (gogoproto.embed) true]; repeated bytes G 2 [(gogoproto.customtype) github.com/gogo/protobuf/test/custom.Uint128, (gogoproto.nullable) false]; }marshalto 插件plugin/marshalto/marshalto.go会生成如下代码func (m *B) Marshal() (dAtA []byte, err error) { size : m.Size() dAtA make([]byte, size) n, err : m.MarshalToSizedBuffer(dAtA[:size]) if err ! nil { return nil, err } return dAtA[:n], nil } func (m *B) MarshalTo(dAtA []byte) (int, error) { size : m.Size() return m.MarshalToSizedBuffer(dAtA[:size]) } func (m *B) MarshalToSizedBuffer(dAtA []byte) (int, error) { i : len(dAtA) _ i var l int _ l if m.XXX_unrecognized ! nil { i - len(m.XXX_unrecognized) copy(dAtA[i:], m.XXX_unrecognized) } if len(m.G) 0 { for iNdEx : len(m.G) - 1; iNdEx 0; iNdEx-- { { size : m.G[iNdEx].Size() i - size if _, err : m.G[iNdEx].MarshalTo(dAtA[i:]); err ! nil { return 0, err } i encodeVarintExample(dAtA, i, uint64(size)) } i-- dAtA[i] 0x12 } } { size, err : m.A.MarshalToSizedBuffer(dAtA[:i]) if err ! nil { return 0, err } i - size i encodeVarintExample(dAtA, i, uint64(size)) } i-- dAtA[i] 0xa return len(dAtA) - i, nil }其工作流程是Marshal先调用Size计算出消息大小并分配恰好大小的缓冲区再调用MarshalToSizedBuffer从缓冲区末尾向前写入MarshalTo则允许调用方传入自己预分配的可复用缓冲区适合高频序列化场景复用内存。Size由 size 插件配合sizer/sizer_all生成调用方还可以用它预先检查复用缓冲区是否足够大。stable_marshaler目前只影响 map 的序列化开启后 map 的键会被排序后按序输出参见 plugin/marshalto/marshalto.go 中IsStableMarshaler分支对sortkeys的调用从而保证同一消息多次 Marshal 产生完全一致的字节流这一点对于需要确定性输出的场景如哈希签名、测试快照很有价值。生成的测试与基准分别由testgen/benchgen扩展控制具体见下文测试与基准生成一节。更规范的 Go 结构告别手工拷贝使用 goprotobuf 时往往会出现字段全是指针、操作不便的问题要么再写一个更顺手的普通结构体并在两者间拷贝要么为了把结构体发到网络上再新建一个 proto 结构。gogoprotobuf 通过以下字段/枚举扩展来消除这种重复劳动名称作用范围类型说明默认值nullableFieldbool若为 false字段生成时不带指针见下方警告trueembedFieldbool若为 true字段以 Go 内嵌字段embedded field方式生成falsecustomtypeFieldstring配合 Marshal/Unmarshal 方法允许在结构体中使用自定义类型但按字节序列化例如 custom.Uuid 或 custom.Fixed128goprotobuf 原生类型customnamebetaFieldstring修改生成字段的 Go 名称特别适用于生成方法与字段名冲突的场景goprotobuf 字段名casttypebetaFieldstring修改生成的字段类型要求该类型可强制转换为原始 proto 字段类型目前不支持 map、struct 和 enumgoprotobuf 字段类型castkeybetaFieldstring修改 map 键的生成类型要求可转换为 proto 字段类型仅支持 mapgoprotobuf 字段类型castvaluebetaFieldstring修改 map 值的生成类型要求可转换为 proto 字段类型仅支持 mapgoprotobuf 字段类型enum_customnamebetaEnumstring设置枚举的类型名若开启了 goproto_enum_prefix该值将作为枚举值的前缀goprotobuf 枚举类型名有助于解决 golint 问题enumdeclbetaEnumbool若为 false生成的输出中不包含该枚举的类型声明要求同时启用 marshaler 与 unmarshalertrueenumvalue_customnamebetaEnum Valuestring修改生成的枚举值名称有助于解决 golint 问题goprotobuf 枚举值名称stdtimeTimestamp Fieldbool将 Well-Known Timestamp 类型改为time.TimeTimestampstddurationDuration Fieldbool将 Well-Known Duration 类型改为time.DurationDurationnullablefalse的警告按照 Protocol Buffer 规范应当能判断一个字段是否被设置。当使用nullablefalse时由于非空字段总是被赋值这一是否设置的语义将丢失。综合示例test/example/example.proto 集中演示了这些扩展message A { option (gogoproto.face) true; option (gogoproto.goproto_getters) false; optional string Description 1 [(gogoproto.nullable) false]; optional int64 Number 2 [(gogoproto.nullable) false]; optional bytes Id 3 [(gogoproto.customtype) github.com/gogo/protobuf/test.Uuid, (gogoproto.nullable) false]; } message B { option (gogoproto.description) true; optional A A 1 [(gogoproto.nullable) false, (gogoproto.embed) true]; repeated bytes G 2 [(gogoproto.customtype) github.com/gogo/protobuf/test/custom.Uint128, (gogoproto.nullable) false]; } message C { optional int64 size 1 [(gogoproto.customname) MySize]; }生成的 Go 结构见 test/example/example.pb.go中type A struct { Description string protobuf:bytes,1,opt,nameDescription json:Description Number int64 protobuf:varint,2,opt,nameNumber json:Number Id github_com_gogo_protobuf_test.Uuid protobuf:bytes,3,opt,nameId,customtypegithub.com/gogo/protobuf/test.Uuid json:Id ... } type B struct { A protobuf:bytes,1,opt,nameA,embeddedA json:A G []github_com_gogo_protobuf_test_custom.Uint128 protobuf:bytes,2,rep,nameG,customtypegithub.com/gogo/protobuf/test/custom.Uint128 json:G ... }可以看到nullablefalse使Description、Number、Id直接成为值类型而非指针embedtrue使消息 B 内嵌了消息 Acustomtype让Id字段类型变为github.com/gogo/protobuf/test.Uuidcustomname则把字段size改名为MySize避免了与Size()方法冲突——这正是 customname 最重要的用途之一。customtype 的用法与约束自定义类型是 gogoprotobuf 的重要能力。定义消息时可以把字段声明为某个 proto 类型更利于跨语言生成代码message CustomType { optional ProtoType Field 1 [(gogoproto.customtype) T]; }也可以直接把字段声明为bytes缺点是其他语言生成 proto 代码时更困难message BytesCustomType { optional bytes Field 1 [(gogoproto.customtype) T]; }无论哪种方式保证自定义类型与期望线格式wire format兼容是用户自己的责任——例如第一种写法中gogoprotobuf 不会替你验证ProtoType与T的线格式一致。假设自定义类型名为T它必须实现以下方法签名custom_types.mdfunc (t T) Marshal() ([]byte, error) {} func (t *T) MarshalTo(data []byte) (n int, err error) {} func (t *T) Unmarshal(data []byte) error {} func (t *T) Size() int {} func (t T) MarshalJSON() ([]byte, error) {} func (t *T) UnmarshalJSON(data []byte) error {} // 仅在开启 compare 选项时需要 func (t T) Compare(other T) int {} // 仅在开启 equal 选项时需要 func (t T) Equal(other T) bool {} // 仅在开启 populate 选项时需要 func NewPopulatedT(r randyThetest) *T {}仓库 test/custom/custom.go 给出了Uint128的完整实现其中Marshal/Unmarshal/Size/MarshalJSON/UnmarshalJSON/Equal/Compare/NewPopulatedUint128一应俱全可作为自定义类型的参考模板。customtype 的警告是你必须自行测试自定义类型的 Marshal、Unmarshal 与 Size 方法在各种边界情况下的行为。stdtime / stdduration直接使用 Go 原生时间类型在 test/types/types.proto 中可以看到这两个选项的典型用法message StdTypes { google.protobuf.Timestamp nullableTimestamp 1 [(gogoproto.stdtime) true]; google.protobuf.Duration nullableDuration 2 [(gogoproto.stdduration) true]; ... google.protobuf.Timestamp timestamp 12 [(gogoproto.stdtime) true, (gogoproto.nullable) false]; google.protobuf.Duration duration 13 [(gogoproto.stdduration) true, (gogoproto.nullable) false]; }开启后google.protobuf.Timestamp字段在 Go 中直接是time.Timegoogle.protobuf.Duration字段直接是time.Duration业务代码无需再与*timestamp.Timestamp、*duration.Duration互转。该文件还演示了wktpointer在 gogoproto/gogo.proto 中定义为 65012——它把DoubleValue、FloatValue、Int64Value等 Wrapper 类型映射为 Go 原生标量指针。仓库中 types 目录与 test/stdtypes 还提供了配套的实现与并发测试。Goprotobuf 兼容性生成与官方等价、按需裁剪的代码gogoprotobuf 与 goprotobuf 兼容因为它本身就兼容 Protocol Buffers 规范相关测试见下文测试与验证。在不使用任何扩展时gogoprotobuf 生成的代码与 goprotobuf 完全一致在此基础上enumprefix、getters、stringer等扩展还可以裁掉 goprotobuf 默认生成的一些冗余代码。名称作用范围类型说明默认值gogoproto_importFilebool若为 false生成的代码导入github.com/golang/protobuf/proto而不是github.com/gogo/protobuf/prototruegoproto_enum_prefixEnumbool若为 false生成的枚举常量名不带消息类型前缀truegoproto_gettersMessagebool若为 false消息不生成 get 方法适合改用 facetruegoproto_stringerMessagebool若为 false消息不生成默认 String 方法适合改用 stringertruegoproto_enum_stringer实验性Enumbool若为 false枚举不生成默认 String 方法适合改用 enum_stringertruegoproto_extensions_mapbetaMessagebool若为 false扩展字段以[]byte生成而非map[int32]proto.Extensiontruegoproto_unrecognizedbetaMessagebool若为 false不生成XXX_unrecognized字段可降低 GC 压力代价是丢失未知字段信息truegoproto_unkeyedalphaMessagebool若为 false不生成XXX_unkeyed字段truegoproto_sizecachealphaMessagebool若为 false不生成XXX_sizecache字段truegoproto_registrationbetaFilebool若为 true生成文件同时向 gogo/protobuf 与 golang/protobuf 注册所有消息和类型当第三方包如 grpc-gateway依赖 golang/protobuf 的注册表时是必需的falsemessage_nameMessagebool若为 true生成XXX_MessageName()方法返回消息名称便于 grpc-gateway 兼容false这些选项在 gogoproto/helper.go 中都有对应实现例如HasGoGetters、EnabledGoStringer、HasUnrecognized、HasSizecache、HasUnkeyed、ImportsGoGoProto、RegistersGolangProto、HasMessageName它们的读取逻辑一致先看消息/枚举级选项未设置再回退到文件级_all选项最后取默认值。goproto_extensions_mapfalse的典型场景是把扩展字段存成原始字节避免为每个扩展维护 maptest/example/example.proto 中的消息 E 即演示了该用法message E { option (gogoproto.goproto_extensions_map) false; extensions 1 to max; }少写代码自动生成辅助方法、接口与工具函数Protocol Buffer 语言结构清晰、易于解析gogoprotobuf 可以据此为结构体自动生成大量辅助代码减少手写样板名称作用范围类型说明默认值gostringMessagebool若为 true生成GoString方法返回一段能复现当前结构体状态的合法 Go 代码falseonlyoneMessagebool若为 true所有字段必须为 nullable且同时只允许一个字段被设置类似 union生成GetValue() interface{}与SetValue(v interface{}) (set bool)两个方法方便与 union 交互falseequalMessagebool若为 true生成Equal方法falsecompareMessagebool若为 true生成Compare方法对快速实现 protobuf 结构体列表的排序非常有用falseverbose_equalMessagebool若为 true为消息生成 verbose equal 方法返回的 error 会精确描述两个结构体中具体哪个元素不相等falsestringerMessagebool若为 true为消息生成String方法falsefaceMessagebool若为 true生成一个函数把满足某接口face的结构体转换为目标结构体该接口包含结构体每个字段的 getter目标结构体本身也生成这些 getter因此它能满足自己的 facefalsedescriptionbetaMessagebool若为 true为消息生成Description方法falsepopulateMessagebool若为 true生成NewPopulatedMessageName函数用于生成测试数据falseenum_stringer实验性Enumbool若为 true为枚举生成String方法false以 equal 插件为例plugin/equal/equal.go对 test/example/example.proto 中的消息 B文件头部声明了equal_all与verbose_equal_all会生成func (this *B) VerboseEqual(that interface{}) error { if that nil { if this nil { return nil } return fmt2.Errorf(that nil this ! nil) } that1, ok : that.(*B) if !ok { ... } ... }Equal只返回布尔值用于快速判断VerboseEqual返回 error 用于定位不相等的具体字段两者配合非常适合调试。Compare 目前存在三个已知局限见 extensions.md 的记录Oneof 尚不支持并非所有 Well Known Types 都支持map 不支持。onlyoneunion 插件则把多字段同时只允许一个被设置的语义封装成GetValue/SetValue仓库 test/example/example.proto 中消息 U 即演示了该用法。测试与基准生成Peace of Mind测试与基准代码同样可以由扩展自动生成为生成的快速编解码代码提供回归保障名称作用范围类型说明默认值testgenMessagebool若为 true生成 proto、json 与 prototext 序列化的测试以及其他已启用插件的测试falsebenchgenMessagebool若为 true生成 proto、json 与 prototext 序列化的基准以及其他已启用插件的基准false测试生成的实际执行路径在 vanity/command/command.go 的Generate中主生成完成后会克隆请求并单独跑一遍testgen.NewPlugin()只有当生成的测试文件内容包含//These tests are generated by github.com/gogo/protobuf/plugin/testgen标记时才追加到输出。因此testgen通常与marshaler、unmarshaler、equal等插件组合使用为每个生成的.pb.go配套产出pb_test.go。更多序列化格式定制 struct tagXML、JSON 等序列化格式通常借助反射读取 Go 结构体上的 tag 来工作。要把生成的 protobuf 结构体导出成符合预期的 XML/JSON 形态需要编辑 tag以下扩展提供了这种能力名称作用范围类型说明默认值jsontagbetaFieldstring若设置双引号内的 json tag 值被替换为该字符串字段名moretagsbetaFieldstring若设置该字符串被追加到 tag 字符串之后空test/tags/tags.proto 展示了它们的组合用法message Outside { optional Inside Inside 1 [(gogoproto.embed) true, (gogoproto.jsontag) ]; optional string Field2 2 [(gogoproto.jsontag) MyField2, (gogoproto.moretags) xml:\,comment\]; oneof filed { string Field3 3 [(gogoproto.jsontag) MyField3, (gogoproto.moretags) xml:\,comment\]; } } message Inside { optional string Field1 1 [(gogoproto.jsontag) MyField1, (gogoproto.moretags) xml:\,chardata\]; }注意jsontag只替换 tag 中json:...双引号内的值甚至可置空字符串以去掉 json tag而moretags是把整段字符串如xml:,comment追加到原有 tag 后面用于补充 json 之外的其他格式所需 tag。文件级选项一条声明全文件生效上文提到的所有布尔型消息扩展与枚举扩展都有一一对应的文件级_all版本包括marshaler_all、sizer_all、protosizer_all、unmarshaler_allunsafe_marshaler_all、unsafe_unmarshaler_all、stable_marshaler_allgoproto_enum_prefix_all、goproto_getters_all、goproto_stringer_all、goproto_enum_stringer_allgoproto_extensions_map_all、goproto_unrecognized_all、goproto_unkeyed_all、goproto_sizecache_allgostring_all、onlyone_all、equal_all、compare_all、verbose_equal_all、stringer_all、enum_stringer_allface_all、description_all、populate_all、testgen_all、benchgen_allenumdecl_all、typedecl_all、messagename_all每个_all选项的效果与其消息级对应项相同只是作用于文件中的所有消息而对应消息级选项可以单独覆盖覆盖为相反值实现文件级默认开启、个别消息单独关闭的粒度控制。这一回退/覆盖逻辑即 gogoproto/helper.go 中proto.GetBoolExtension(message.Options, E_Xxx, proto.GetBoolExtension(file.Options, E_XxxAll, default))的三层取值模式。例如 test/example/example.proto 文件头同时开启了gostring_all、equal_all、verbose_equal_all、stringer_all、populate_all、testgen_all、benchgen_all、marshaler_all、sizer_all、unmarshaler_all并把goproto_stringer_all设为 false用 stringer 替代默认 String 方法个别消息再单独叠加face、description、onlyone等消息级选项是一个文件级 消息级混合使用的完整范本。动手实践如何在一个 proto 文件中启用扩展参考 test/example/Makefile完整的生成流程如下在.proto文件头部导入扩展定义import github.com/gogo/protobuf/gogoproto/gogo.proto;按需声明文件级或消息/字段/枚举级选项见上文各表。生成代码时把 gogo.proto 所在路径与你的 proto 所在路径一起加入--proto_path并指定--gogo_outregenerate: (protoc -I. -I$(GOPATH)/src/github.com/gogo/protobuf/protobuf -I$(GOPATH)/src --gogo_out. example.proto)其中-I$(GOPATH)/src/github.com/gogo/protobuf/protobuf用于找到google/protobuf/descriptor.proto等官方定义-I$(GOPATH)/src用于找到github.com/gogo/protobuf/gogoproto/gogo.proto在现代 Go modules 环境下可相应替换为模块缓存路径或 vendor 路径。使用仓库根目录 Makefile 的make install安装全部代码生成器protoc-gen-gogo、protoc-gen-gofast、protoc-gen-gogofaster、protoc-gen-gogoslick等或用make regenerate重新生成仓库内全部测试代码。仓库还提供protoc-gen-comboprotoc-gen-combo/combo.go它会自动把unmarshaler_all/marshaler_all的四种组合neither / marshaler / unmarshaler / both分别生成到combos/子目录用于测试不同组合下的行为一致性——从 test/Makefile 的protoc-gen-combo --defaultfalse ... thetest.proto可见其用法。测试与验证扩展机制的正确性由仓库内的大规模测试保障extensions.md 的 Tests 一节常规测试make tests对应 Makefile 中的go build ./test/enumprefix、go test ./...与 stdtypes 专项测试一些特殊/边界测试make testall会额外拉取github.com/golang/protobuf/proto并运行 protoc-gen-gogo、vanity、registration、conformance、issue427 等专项测试与github.com/golang/protobuf的兼容性测试、跨版本测试、GRPC 测试与 go-fuzz 模糊测试由 gogo 组织的独立子项目承担harmonytests、grpctests、fuzztests 等因为其分别依赖 goprotobuf、大量 grpc 库与 fuzz 基础设施。此外make benchMakefile会编译 test/mixbench/mixbench.go 并输出反射实现与生成代码实现的基准对比文件见 test/mixbench 下的marshal.txt/unmarshal.txt/marshaler.txt/unmarshaler.txt等可配合 benchcmp 查看具体提速幅度。小结gogoprotobuf 的扩展体系可以分为四层能力更快marshaler/unmarshaler/sizer/protosizer 等生成手写编解码代码、更顺手的 Go 结构nullable/embed/customtype/casttype/stdtime 等消除指针与手工拷贝、更省事gostring/equal/compare/stringer/face/populate 等自动生成辅助方法与测试、以及更兼容goproto_* 系列控制与标准 goprotobuf 的行为差异。在实际项目中建议从文件级_all选项起步统一开启所需能力再针对个别消息用消息级选项微调并配合testgen/benchgen为生成代码建立回归与性能保障。赞分享序列化【免费下载链接】protobuf[Deprecated] Protocol Buffers for Go with Gadgets项目地址https://gitcode.com/gh_mirrors/proto/protobuf点击查看免费下载相关推荐OpenAPI代码生成全攻略从接口自动化到Maven插件实战指南OpenAPI代码生成全攻略从接口自动化到Maven插件实战指南 作为API开发者你是否常因手动编写接口代码而效率低下是否在OpenAPI规范更新后面临开发工具代码生成API设计CLIUnkey OpenAPI 规范拆分实践从多文件结构到 Go 代码生成Unkey OpenAPI 规范拆分实践从多文件结构到 Go 代码生成 Unkey 作为面向现代 API 的开发者平台其公共 API 文档以 OpenAPI后端API网关认证鉴权aiXcoder-7B数据结构代码生成从基础到实战的完整指南aiXcoder 7B数据结构代码生成从基础到实战的完整指南 还在为编写复杂数据结构代码而烦恼aiXcoder 7B作为当前最先进的代码大模型在数据结构代上一篇PyTorch3D Implicitron 神经辐射场NeuralRadianceField隐式函数源码深度解析下一篇三阶解锁方案RDP Wrapper Library远程桌面并发会话技术实现指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考