开发环境：

• IDE: VSCode

• VSCode的扩展插件：vscode-proto3和Clang-Format这两个扩展

• Windows还需要安装Clang，Windows 64位系统的地址如下：Clang for Windows (64-bit)(http://llvm.org/releases/3.7.0/LLVM-3.7.0-win64.exe)；Mac：brew install clang-format 。

  
  

第一个例子

1. 这行代码表示我们使用的是语法是proto3，之前还有一个proto2；如果你不写这一行，那么protocol buffer编译器会认为你采用的是proto2。这个必须是文件的第一个非空非注释行。
   

2. 这里是定义了一个消息名称为FirstMessage，类型是message。它里面定义了三个字段，它们都是标量类型（Scalar Type），你也可以定义复合类型，这个以后再说。

3. 是指字段（Field）的类型

4. 字段的名称

5. 字段的数值（也叫Tag），这个数字是唯一的。它们是用来在信息格式里识别你的字段的，一旦该类型被使用了，那么这个数字就不要再改变了。

01

标量类型

• 数值型：数值型有很多种形式：double, float, int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64。根据需要选择对应的数值类型。

• 布尔型：bool型可以有True和False两个值。

• 字符串：string表示任意长度的文本，但是它必须包含的是UTF-8编码或7位ASCII的文本，长度不可超过232。

•  字节型：bytes可表示任意的byte数组序列，但是长度也不可以超过232  ，最后是由你来决定如何解释这些bytes。例如你可以使用这个类型来表示一个图片。

  
  

做个例子

可以自己做一个例子，需求是这样的：这个信息表示的是一个人Person，使用proto3语法，字段如下：ID，姓名，身高，体重，头像，电子邮件，邮件是否已验证。

这个应该没有什么难度，不过要注意一下别忘记标点符号。

02

关于字段

字段的数值（Tag）

      在Protocol Buffers里面，字段的名其实没那么重要，但是写C#代码的时候，字段名还是很重要的。

对于protobuf来说，这个tag是更为重要的。

      可以使用的最小的tag数值是1，最大值是229 - 1, 或者 536,870,911。但是你不可以使用19000到19999之间的数，这部分数是保留的。

      还有一点值得注意的是：

      从1到15的Tag数只占用1个字节的空间，所以它们应该被用在频繁使用的字段上。而从16到2047，则占用两个字节，它们可以用在不频繁使用的字段上。

字段规则

      protobuf的字段必须满足以下两个规则之一：

单数字段（Singular）

      大概意思就是指这个字段只能出现0或1次（不能超过一次），这也是proto3的默认字段规则。

重复字段（Repeated）

      与singular相对的就是repeated。如果你想做一个list或数组的话，你可以使用重复字段这个概念。这个list可以有任何数量（包括0）的元素。它里面的值的顺序将会得到保留。

Repeated Fields 例子

      还是使用前面的Person这个例子，我们在里面添加一个repeated字段（电话号码）：

      就是在前面加上repeated这个关键字即可。

      在proto3里面，标量类型的repeated字段采用的是packed编码。

注释

      proto文件里可以添加注释。它们通常被当作你定义的这些消息的文档。

      注释很简单，还是两种形式，直接看代码就明白了：

保留的字段

      保留的字段如果你对你定义的消息类型进行了更新，例如删除某个字段或者注释掉某个字段，那么其它开发者在以后更新这个消息类型的时候可能会重新使用被你删除/注释掉的字段的数值（tag）。如果以后还需要使用这个消息类型的老版本的proto文件，那么这将会引起严重的问题，例如数据损坏、隐私漏洞等等。

      那么一种避免此类事情发生的解决办法就是将你删除/注释掉的这些字段的数值（或/并且包括字段名，因为字段名可引起JSON序列化的问题）标记为reserved，如果其他人再使用这个数值作为字段标识符，那么编译器就会有错误提示：

      注意，不可以把reserved数值和字段名放在同一个reserved语句里。

字段的默认值

当消息被解析的时候，如果编码的消息里不含有特定的一个singular元素，那么在被解析对象里相应的字段就会被设为默认值。

常用类型的默认值如下：

• string：空字符串

• bytes：空的byte数组

• bool：false

• 数值型：0

• 枚举enum：枚举里定义的第一个枚举值，值必须是0

• repeated：通常是相应开发语言里的空list

• 还有个消息类型的字段，它的默认值和开发语言有关，这个以后再说。

03

枚举

      之前说了，枚举里面定义的第一个值就是这个枚举的默认值。

      Enum的tag必须从0开始，所以0就是枚举的数值默认值。

继续上个例子

      我们对Person添加一个枚举类型的字段：性别 Gender：

      首先需要定义枚举类型，这里定义了一个枚举，名称是Gender，里面有3个值，默认值是NOT_SPECIFIED，数值默认值就是0。

      然后使用这个枚举类型定义了一个字段，名称为gender，tag数为10。

为枚举值起别名

      枚举值是可以起别名的，起别名的作用就是允许两个枚举值拥有同一个数值。

      要想起别名，首先需要设置allow_alias这个option为true：

      然后我们为FEMALE这个枚举值起了一个别名叫做WOMAN，它们的数值是一样的。同样的MAN是MALE的数值也是一样的。

      枚举里面的常量的值必须不能超过32位整型的数值，不建议使用负数。

      枚举可以定义在message里面，也可以在外边单独定义以便复用。如果另一个消息想使用Person里面这个Gender枚举，那么可以使用Person.Gender这种形式。

      针对枚举值被删除/注释掉这种情况，它也可以使用reserved：

数值和常量名也必须分开使用两个reserved语句。

其中max表示可能的最大的值。

今天先到这。。

---

.NET社区新闻，深度好文，欢迎访问公众号文章汇总 http://www.csharpkit.com