protocol buffers生成go代码原理
protocol buffers生成go代码原理
本文描述了protocol buffers使用.proto文件生成pb.go文件的过程
编译器
编译器需要插件来编译环境，使用如下方式安装插件：go get github.com/golang/protobuf/protoc-gen-go
使用.proto生成的文件相比输入文件有如下两处变更：
-
- 生成文件的文件名为：输入文件的扩展名.pb.go，如使用player.proto生成的文件名为player.pb.go
- 生成文件的路径为--go_out指定的文件
当执行如下命令时：
protoc --proto_path=src --go_out=build/gen src/foo.proto src/bar/baz.proto编译器会读取src/foo.proto src/bar/baz.proto，并分别生成build/gen/foo.pb.go and build/gen/bar/baz.pb.go。编译器会自动生成build/gen/bar目录，但不会生成build或build/gen目录。
包
如果.proto文件包含包定义，则生成的代码会使用.proto的package，与go的package处理类似，会将package名字中的"."转换为"_"。如proto package名为example.high_score，对应生成的代码的package name为example_high_score。
使用go_package选项可以替换默认条件下.proto生成的package name。如下生成的go package为“hs".
package example.high_score;
option go_package = "hs";如果.proto文件中没有包含package声明，则生成的代码会使用文件名(处理方式类似go package name)
消息
下面是一个简单的message
message Foo {}protocol buffer 编译器会生成一个struct，名为Foo。A *Foo实现了该接口的方法。下述成员会出现在所有message生成的go代码中
type Foo struct {
}
// Reset sets the proto's state to default values.
func (m *Foo) Reset() { *m = Foo{} }
// String returns a string representation of the proto.
func (m *Foo) String() string { return proto.CompactTextString(m) }
// ProtoMessage acts as a tag to make sure no one accidentally implements the
// proto.Message interface.
func (*Foo) ProtoMessage() {}内嵌类型
如下内嵌场景下会生成2个独立的struct，Foo和Foo_Bar
message Foo {
message Bar {
}
}Well_known 类型
protocol buffer的预定义消息集合，称为well_known types(WKTs)。这些类型在与其他服务交互时比较好用。如Struct消息表示了任意的C风格的struct。
为WTKs预生成的go代码作为Go protobuf library的一部分发布。如给出一个message
import "google/protobuf/struct.proto"
import "google/protobuf/timestamp.proto"
message NamedStruct {
string name = 1;
google.protobuf.Struct definition = 2;
google.protobuf.Timestamp last_modified = 3;
}生成的Go代码如下：
import google_protobuf "github.com/golang/protobuf/ptypes/struct"
import google_protobuf1 "github.com/golang/protobuf/ptypes/timestamp"
...
type NamedStruct struct {
Name string
Definition *google_protobuf.Struct
LastModified *google_protobuf1.Timestamp
}字段
生成的go字段名称遵循驼峰命名法，规则如下：
-
- 首字母大写，如果首字符是下划线，则使用大写X替换该下划线
- 如果字符内部的下划线后跟着小写的字母，则移除该下划线，并将原来下划线后面的字母大写
如foo_bar_baz变为FooBarBaz，_my_field_name_2变为XMyFieldName_2
Singular Scalar Fields (proto3)
int32 foo = 1;编译器会生成一个包含名为int32字段，名为Foo的struct，以及一个名为GetFoo()的方法，该方法会返回Foo中定义的int32的值，或默认值(如果设置初始值)
Singular Message Fields
message Bar {}message Baz {
Bar foo = 1;
}针对message Baz，编译器会生成如下struct，以及一个func (m *Baz)GetFoo() *Bar的函数。
type Baz struct {
Foo *Bar //结构体使用指针
}Repeated Fields
message Baz {
repeated Bar foo = 1;
}生成如下struct。类似地，如果字段定义为 repeated bytes foo = 1，编译器会生成名为Foo，含[][]byte字段的Go struct；字段定义为 repeated MyEnum bar = 2，则会生成名为Bar，包含[]MyEnum字段的struct
type Baz struct {
Foo []*Bar //相比不带repead的，多了"[]"
}Map Fields
message Bar {}
message Baz {
map<string, Bar> foo = 1;
}编译器生成如下struct
type Baz struct{
Foo map[string]*Bar //map中的结构体也是指针表达方式
}Oneof Fields
针对oneof字段，protobuf编译器会生成接口类型 isMessageName_MyField。此外oneof中的每个singular字段会生成struct，isMessageName_MyField接口。如下oneof：
package account;
message Profile {
oneof avatar {
string image_url = 1;
bytes image_data = 2;
}
}编译器会生成struct：
type Profile struct {
// Types that are valid to be assigned to Avatar:
// *Profile_ImageUrl
// *Profile_ImageData
Avatar isProfile_Avatar `protobuf_oneof:"avatar"`
}
type Profile_ImageUrl struct {
ImageUrl string
}
type Profile_ImageData struct {
ImageData []byte
}*Profile_ImageUrl 和*Profile_ImageData都使用一个空的isProfile_Avatar()实现了isProfile_Avatar 编译器同时会生成func (m *Profile) GetImageUrl() string 和func (m *Profile) GetImageData() []byte
如下展示了如何设置字段：
p1 := &account.Profile{
Avatar: &account.Profile_ImageUrl{"http://example.com/image.png"},
}
// imageData is []byte
imageData := getImageData()
p2 := &account.Profile{
Avatar: &account.Profile_ImageData{imageData},
}可以使用如下来处理不同的message类型
switch x := m.Avatar.(type) {
case *account.Profile_ImageUrl:
// Load profile image based on URL
// using x.ImageUrl
case *account.Profile_ImageData:
// Load profile image based on bytes
// using x.ImageData
case nil:
// The field is not set.
default:
return fmt.Errorf("Profile.Avatar has unexpected type %T", x)
}Enumerations
message SearchRequest {
enum Corpus {
UNIVERSAL = 0;
WEB = 1;
IMAGES = 2;
LOCAL = 3;
NEWS = 4;
PRODUCTS = 5;
VIDEO = 6;
}
Corpus corpus = 1;
...
}protocol buffer会生成一个类型以及一系列该类型表示的常量。在message内部的enums，type的名称会以message名称开头：
type SearchRequest_Corpus int32
const (
SearchRequest_UNIVERSAL SearchRequest_Corpus = 0
SearchRequest_WEB SearchRequest_Corpus = 1
SearchRequest_IMAGES SearchRequest_Corpus = 2
SearchRequest_LOCAL SearchRequest_Corpus = 3
SearchRequest_NEWS SearchRequest_Corpus = 4
SearchRequest_PRODUCTS SearchRequest_Corpus = 5
SearchRequest_VIDEO SearchRequest_Corpus = 6
)package级别的enum
enum Foo {
DEFAULT_BAR = 0;
BAR_BELLS = 1;
BAR_B_CUE = 2;
}Go类型以原来的enum，该类型还有一个String()方法来返回给定值的名字，Enum()方法初始化并分配给定值的内存，返回相应的指针。
type Foo int32
func (Foo) Enum() *Fooprotocol buffer编译器也会整数到字符串名称以及名称到数值的对应关系
var Foo_name = map[int32]string{
0: "DEFAULT_BAR",
1: "BAR_BELLS",
2: "BAR_B_CUE",
}
var Foo_value = map[string]int32{
"DEFAULT_BAR": 0,
"BAR_BELLS": 1,
"BAR_B_CUE": 2,
}.proto允许多enum的数值相同。由于多名称对应一个数值，逆向对应关系则是数值与.proto文件中出现的第一个名称相对应（一个对应关系）。
service
Go代码生成器默认不会为services生成代码。如果使能了gRPC插件，则可以支持个RPC代码的生成。