ProtoBuffer消息设计经验

message设计

分类

消息用于client与server之间的交互，一般都是请求-响应的组合。写代码的一大原则是：类、函数等的命名尽量能体现其含义。所以，个人习惯在消息编号以及消息结构体中通过后缀REQ、Req、RSP、Rsp来却分请求、响应。有的响应没有响应内容，无须定义响应的message，这个就相当于一个ack消息。所以可以通过后缀来表示message的分类：

_REQ、Req:表示请求
_RSP、Rsp:表示请求的响应，带有响应消息
_ACK、Ack:表示请求的确认，无响应消息

例如：

message Test1Req{    
    optional uint64 uid    = 1;  
    optional uint32 type    = 2; 
}

message Test1Rsp{
    optional int32 test    = 1;     
}

message Test2Req{    
    optional uint64 uid    = 1;  
    optional uint32 type    = 2; 
}

message Test2Rsp{
    optional int32 test    = 1;     
}

抽象

消息往往会有很多公用的字段，特别是响应的消息，比如消息类型、消息的序列号、响应的结果（错误码）、响应结果的描述等，可以定义一个总的Message，将公共的字段提取出来放到Message中。例如：

message Message{
   required MAGIC type = 1;
   required fixed32 seq = 2;
   optional fixed32 errCode = 3;
   optional bytes errMsg = 4;
   optional Test1Req test1Req = 5;
   optional Test1Rsp test1Rsp = 6;
   optional Test2Req test2Req = 7;
   optional Test2Rsp test2Rsp = 8;
}

这样做的好处是：

（1）更加抽象
（2）所有消息针对Message parse一次即可，不需要再分别去parse test1Req、test1Rsp、test2Req、test2Rsp

上述代码中，请求中一般没有errcode字段，所以可以进一步抽象出Request和Response两个消息：

message Request{
    optional Test1Req test1Req = 1;
    optional Test2Req test2Req = 2;
}

message Response{
    required fixed32 errCode = 1;
    optional bytes errMsg = 2;
    optional Test1Rsp test1Rsp = 1;
    optional Test2Rsp test2Rsp = 2;
}

这样的话，如有需要，请求的公用字段都加到Request中，响应的公用字段都加到Response中，两者相同的公用字段都加到上层的Message中。Message就变成如下：

message Message{
   required MAGIC type = 1;//消息类型，MAGIC枚举
   required fixed32 seq = 2;
   optional Request request = 3;
   optional Response response = 4;
}

使用enum定义message的类型

接下来要为每一个消息定义一个消息类型，一般建议用enum定义，例如定义一个MAGIC的enum：

enum MAGIC{
    MAGIC_TEST1_REQ = 0x00001001;
    MAGIC_TEST1_RSP = 0x00001002;
    MAGIC_TEST2_REQ  = 0x00001003;
    MAGIC_TEST2_RSP  = 0x00001004;

}

本人喜欢用MAGIC这个命名。MAGIC（幻数）是计算机编码中的一个术语，直接翻译为魔幻一般的数字，多好听。
至于类型的数值，可以自定义，比如从1开始递增。

这样定义完后，拿到protobuffer后的字符串，一次解析，再根据type即可取出响应的对象

    //代码片段      
    msg := Message{}
    err := proto.Unmarshal(buf[:len], &msg)
    if err != nil {
        //错误处理
        return err
    }

    if msg.GetType() ==  MAGIC_TEST1_REQ{
        req := msg.GetRequest().GetTest1Req()//直接取出Test1Req对象
        //handle

    }
    if msg.GetType() ==  MAGIC_TEST2_REQ{
        req := msg.GetRequest().GetTest2Req()//直接取出Test2Req对象
        //handle
    }
    if msg.GetType() ==  MAGIC_TEST1_RSP{
        rsp := msg.GetRequest().GetTest1Rsp()//直接取出Test1Rsp对象
        //handle
    }

错误码定义

错误码定义也用enum。错误码定义的原则是：通过错误码就能直接识别是哪个模块产生的，这样定位问题的时候就直指目标。可以通过数字区间来定义不同模块的错误码：

enum ERR_CODE {
       CLIENT_ERR_REFUSE = 100001;//客户端的错误码从100000-19999
       CLIENT_ERR_ACCEPT = 100002;
       SERVER1_ERR_STOP = 200001;//模块1的错误码从200000-29999
       SERVER2_ERR_OVERLOAD = 300001;//模块2的错误码从300000-39999
 }

序列化后数据的封包和解包

• 封包：定义好的Message对象通过encode之后序列化成一段buf(字符串)，加上长度一起封包。一般包头前两个字节用来标示buf的长度，后面接上buf。然后发送给对端。

• 解包：取前两个字节先解出长度，再读入相应长度的buf，parse成Message对象即可。

proto的维护

实际应用中，不同的模块增加、修改消息或者字段是很频繁的事情。如果多个人修改proto文件，容易导致不同模块上运行不同版本proto，会有一些不可预估的风险。所以一般指定一个人负责proto的维护，所有proto的修改都由一个人完成，且制定proto更新时涉及模块的发版顺序。