protobuf语法详解

标签: protocol buffer protobuf
5人阅读 评论(0) 收藏 举报
分类:
文章开头,先贴一段protobuf的定义语法
option java_outer_classname = "StudentEntity";  
message Student {  
  required int32 id = 1;  
  required string name = 2;  
  optional string nickname = 3 [default=""];  
}  
一、message

protobuf中定义一个数据结构需要用到关键字message,这一点和java的class是差不多的。

二、标识号

在消息的定义中,每个字段等号后面都有唯一的标识号,用于在反序列化过程中识别各个字段的,一旦开始使用就不能改变。

三、字段规则

字段规则有三种:

  1. required:该规则规定,消息体中该字段的值是必须要设置的。
  2. optional:消息体中该规则的字段的值可以存在,也可以为空,optional的字段可以根据defalut设置默认值。
  3. repeated:消息体中该规则字段可以存在多个(包括0个),该规则对应java的数组。
四、数据类型

数据类型没什么好说的,都是常见的数据类型,具体见下面表格


五、枚举及其它消息类型的使用
option java_outer_classname = "StudentEntity";  
message Student {  
  required int32 id = 1;  
  required string name = 2;  
  optional string nickname = 3 [default=""];  
  enum Age{
    男=1;
    女=2;
    }
  required Age age=4;
  required Class class=5;
} 

message Class{
  required int32 id=1;
  required string name=2;
}

除此之外,message还支持map类型的字段,声明如下

map<int32, string> m = N;

如果需要引用的message是写在别的.proto文件中,可以通过import "xxx.proto"来进行引入。

六、嵌套
option java_outer_classname = "StudentEntity";  
message Student {  
  required int32 id = 1;  
  required string name = 2;  
  optional string nickname = 3 [default=""];  
  enum Age{
    男=1;
    女=2;
    }
  required Age age=4;
  message Class{
  required int32 id=1;
  required string name=2;
  }
  required Class class=5;
} 
七、Option

在消息定义前,可以通过option来进行配置,常用的两个option:

  1. option java_package="xxx/xxx" 该选项指定了java文件生成的路径
  2. option java_outer_classname="xxx" 该选项制定了生成的java类名

更多选项可以参考

八、message的更新

message定义后如果需要修改,为了保证之前的序列化和反序列化能够兼容于新的message,message的修改需要满足以下规则:

  • 不可以修改已存在域中的标识号
  • 所有新增添的域必须是 optional 或者 repeated。这就意味着,只要不遗失已经定义的required域,旧序列化信息可以被新的代码解析。为了新代码可以正常解析旧代码提供的序列,我们需要在更新的时候向新域中添加一些默认值(默认值是不会被传递的,仅仅在本地保存,也就是说不同版本的代码对同一个域可能读取不同的值)。同样,新代码产生的序列化文件也可以被旧代码解析,解析时旧代码会忽略新添加的域,这些域在解析时不会被丢弃,在旧代码序列化时,这些域会跟随其他域一起被序列化。将序列化之后的文件传递给新代码。这些新域也是有效的。
  • 非required域可以被删除。但是这些被删除域的标识号不可以再次被使用。
  • 非required域可以被转化,转化时可能发生扩展或者截断,此时标识号和名称都是不变的。
  • int32, uint32, int64, uint64 和bool都是相互兼容的。这就意味着这些类型之间可以相互转换,并且都是向前,向后兼容的。如果我们设定的类别不足以表示数字,那么就会发生类似于C++的截断。
  • sint32和sint64是相互兼容的,并且不和其他整数类型兼容
  • string 在UTF-8编码时与bytes相互兼容
  • 嵌套Message在编码方式相同的情况下兼容bytes
  • fixed32兼容sfixed32。 fixed64兼容sfixed64。
  • optional兼容repeated。发送端发送repeated域,用户使用optional域读取,将会读取repeated域的最后一个元素。
  • 改变默认值通常来说是没有问题的。但值得注意的是:只要用户的版本没有更新,那么在没有设置这个域的情况下,用户依旧是读取原来的默认值。
  • 枚举类型兼容int32, uint32, int64, uint64(注意如果值和类型不匹配则会发生截断),所以我们需要注意,用户端可能在解析之后对这些值进行非enum的一些处理。通常,没能识别(不在enum定义的集合内)的enum值将会被丢弃,此时如果使用has方法,则会返回false。用getter方法读取这个值,会返回enum 列表的第一个值,如果定义了default则返回default的值。在repeated enum域里面所有不可识别的元素都将被移除这个列表,除非是整数域,它会保留整数域的值。因此,我们在提升一个整数类型为enum类型的时候要注意是否超过其值域。
  • 在现有的java和c++应用中,当不能识别的enum被移除时,它其实是和其他不可识别的元素一起保存在了“未知域(unknown fields)”。当客户端在此解析未知域的时候,如果能够识别,则有可能发生一些奇怪行为。在optional域中,在原来消息解析完毕并写入新的数据之后,用户依然可以读取原来的消息。在repeated域中,旧的值将会出现在新添加的值之后,因此其顺序不是固定的。


查看评论

在VC2015里使用protobuf协议

-
  • 1970年01月01日 08:00

Protobuf语言指南——.proto文件语法详解

Protobuf语言指南 .proto文件语法详解
  • u014308482
  • u014308482
  • 2016-10-28 17:23:07
  • 23250

protobuf协议基础介绍

Protocol Buffers 介绍主题 l  Protocol Buffers简介 l  定义一个.proto文件 l  Message的使用 l  消息的编码机制 l  使用时注意事...
  • zhaozheng7758
  • zhaozheng7758
  • 2011-09-05 11:08:21
  • 11813

Protobuf 语法指南

转自:  http://colobu.com/2015/01/07/Protobuf-language-guide/ Protobuf 语法指南 目录 [−] 定义一个消息类型 ...
  • junjun331
  • junjun331
  • 2015-11-10 11:31:24
  • 3208

Protobuf3语言指南

定义一个消息类型 指定字段类型 分配标识号 指定字段规则 添加更多消息类型 添加注释 保留标识符(Reserved) 从.proto文件生成了什么? 标量数值类型 默认值 枚举 使用其他消息类型 ...
  • u011518120
  • u011518120
  • 2017-01-25 22:14:47
  • 33439

editplus的ice语法文件和模板文件。

editplus的模板文件和语法文件使用方式自己去百度。 模板文件为。 #pragma once [["cpp:include:test.pb.h"]] [["cpp:include:S...
  • wzjin
  • wzjin
  • 2015-06-10 18:37:21
  • 991

Protocol Buffers(Protobuf) 官方文档--Protobuf语言指南

约定:为方便书写,ProtocolBuffers在下文中将已Protobuf代替。 本指南将向您描述如何使用protobuf定义i结构化Protobuf数据,包括.proto文件语法和如何使用.pr...
  • YiLuSuiYun
  • YiLuSuiYun
  • 2014-03-19 23:38:15
  • 4592

[翻译] Protobuf 语言指南 ( proto 2 )

定义一个消息 首先来看一个简单的例子,定义一个搜索请求的消息格式,每个消息包含一个请求字符串,你感兴趣的页数和每页的结果数。下面是在.proto 文件中定义的消息。 message SearchR...
  • cchd0001
  • cchd0001
  • 2016-02-16 16:14:11
  • 7501

ProtoBuf入门

From:http://www.open-open.com/lib/view/open1418518348136.html 背景:碰到一个协议,使用了ProtoBuf,就想对此做个了解!:) 正文: ...
  • u013427969
  • u013427969
  • 2016-10-14 00:32:37
  • 686

protobuf---真正-- 在IOS中的使用

转自  http://blog.sina.com.cn/s/blog_74e9d98d0101jood.html 1.首先要下载下载Protocol Buffers:http://code.goog...
  • akka123
  • akka123
  • 2016-05-13 00:27:08
  • 453
    个人资料
    持之以恒
    等级:
    访问量: 1万+
    积分: 225
    排名: 33万+
    文章存档
    最新评论