Protobuf使用手册可编辑范本.doc

Pｒotobｕf使用手册
定义。ｐroto文件
首先我们需要编写一个ｐroto文件，定义我们程序中需要处理的结构化数据,在protobuｆ的术语中，结构化数据被称为Mｅssage．proｔo文件非常类似jａvａ或者C语言的数据定义,可以使用C或Ｃ++风格的注释。下面是一个protｏ文件的例子.
ｐａｃｋagetutoｒiａl;

optionjava_paｃkａｇe=”cｏｍ．ｅxampｌｅ。ｔuｔoｒｉal＂；
opｔionjaｖa_outｅr＿ｃlａssnaｍe=”AｄｄrｅsｓBｏｏｋPｒotoｓ”;

ｍessａｇeＰｅrson{
reｑuiredstrｉngｎａme＝1;
ｒeqｕｉredint32id=2;//ＵniｑueIDnuｍｂerｆortｈispeｒson。
ｏpｔｉｏnalｓtriｎgｅｍａil=3；

eｎuｍＰｈoneＴype{
ＭOBILＥ=0；
HOME=1；
WＯRＫ=2；
}

ｍｅsｓａｇePhoneＮumber{
requiredｓｔringnumber=１；
optioｎａlＰhoneTypｅtype=２[dｅｆａulｔ=HOＭE];
}

repｅatedPｈoｎeＮumｂerｐhｏne＝４;
}

//Ｏｕraddresｓbｏokfｉｌeisjustoneoｆthｅｓe。
meｓsageAddresｓBook｛
repｅatedPeｒsoｎｐerｓon＝1;
｝一个pｒoｔo文件主要包含ｐａｃkagｅ定义、ｍeｓｓａgｅ定义和属性定义三个部分，还有一些可选项。
定义packａge
Package在c++中对应nａmespaｃe.
对于Jａva，包声明符会变为jａva的一个包,除非在。pｒoto文件中提供了一个明确有ｊava_ｐaｃｋage.
定义meｓsagｅ
Ｍeｓsage在C++中对应ｃlass。Message中定义的全部属性在claｓs中全部为private的。
Meｓｓａｇe的嵌套使用可以嵌套定义，也可以采用先定义再使用的方式。
Ｍessage的定义末尾可以采用jａva方式在不加“;",也可以采用Ｃ++定义方式在末尾加上“；",这两种方式都兼容,建议采用ｊａvａ定义方式。
向.prｏto文件添加注释，可以使用Ｃ/C++/javａ风格的双斜杠(/／)语法格式。
定义属性
属性定义分为四部分:标注+类型＋属性名+属性顺序号+［默认值］，其示意如下所示。
标注类型属性名属性顺序号[默认值]requiｒeｄｓtrｉｎgｎaｍe＝1［ｄｅfaｕlｔ=””］；其中属性名与Ｃ++和ｊava语言类似,不再解释；下面分别对标注、类型和属性顺序号加以详细介绍。
其中包名和消息名以及其中变量名均采用jaｖa的命名规则——驼峰式命名法，驼峰式命名法规则见附件1。
标注
标注包括“required”、“optionａl”、“reｐｅated”三种，其中
required表示该属性为必选属性,否则对应的ｍesｓage“未初始化”,ｄebuｇ模式下导致断言,ｒelｅase模式下解析失败；
ｏｐtｉoｎal表示该属性为可选属性,不指定，使用默认值(int或者char数据类型默认为0，string默认为空,boｏl默认为falｓe，嵌套mｅsｓａgｅ默认为构造，枚举则为第一个)
repeateｄ表示该属性为重复字段，可看作是动态数组,类似于C++中的vector.
如果为ｏｐｔional属性,发送端没有包含该属性，则接收端在解析式采用默认值。对于默认值,如果已设置默认值,则采用默认值，如果未设置,则类型特定的默认值为使用,例如sｔriｎｇ的默认值为””。
类型
Protobuｆ的属性基本包含了c＋＋需要的所有基本属性类型。
protｏbｕf属性C++属性ｊaｖa属性备注doｕbｌedoubleｄouｂｌｅ固定8个字节floaｔfloaｔｆloａt固定４个字节iｎt３2int３2ｉnt32使用变长编码,对于负数编码效率较低,如果经常使用负数,建议使用sｉnt32int64int64int6４使用变长编码,对于负数编码效率较低，如果经常使用负数，建议使用sinｔ６4uint３2ｕｉnt32int使用变长编码uint６4uiｎt64long使用变长编码ｓiｎt３2iｎt3２inｔ采用ziｇｚag压缩，对负数编码效率比iｎt3２高ｓｉnｔ64inｔ64ｌong采用ziｇzａｇ压缩,对负数编码效率比inｔ6４高fｉｘeｄ32ｕinｔ32ｉｎt总是4字节，如果数据＞2^28,编码效率高于unit32fixｅd64uｉnt64lｏng总是8字节,如果数据〉２^56，编码效率高于uniｔ32ｓｆｉxed32int３2int总是4字节sfixed６4inｔ６4lｏnｇ总是8字节bｏoｌｂｏolｂｏｏleaｎstriｎgｓtｒｉ