Thrift之TProtocol类体系原理及源码详细解析之二进制协议类TBinaryProtocolT（TBinaryProtocol）

　　我的新浪微博：http://weibo.com/freshairbrucewoo。

欢迎大家相互交流，共同提高技术。

 

这个协议是Thrift支持的默认二进制协议，它以二进制的格式写所有的数据，基本上直接发送原始数据。因为它直接从TVirtualProtocol类继承，而且是一个模板类。它的模板参数就是一个封装具体传输发送的类，这个类才是真正实现数据传输的。这个类的定义上一节举例已经出现过了就不在列出来了。

下面我就结合scribe的Log函数执行的具体过程来分析使用这个协议所执行的功能，看看二进制协议是怎样工作的。

RPC调用使用到协议部分主要是在发送函数相关信息到服务器和接收服务器返回结果。现在我就结合Log函数的实现代码具体分析。首先看看Log函数的发送相关信息函数send_log（在文件scribe.cpp）：

 1 void scribeClient::send_Log(const std::vector<LogEntry> & messages)

 2 

 3 {

 4 

 5   int32_t cseqid = 0;

 6 

 7   oprot_->writeMessageBegin("Log", ::apache::thrift::protocol::T_CALL, cseqid);//写入函数调用消息

 8 

 9   scribe_Log_pargs args;

10 

11   args.messages = &messages;

12 

13   args.write(oprot_);//调用参数类自己的写入函数写入参数到服务器

14 

15   oprot_->writeMessageEnd();//写入消息调用写入

16 

17   oprot_->getTransport()->writeEnd();//结束传输层的写入

18 

19   oprot_->getTransport()->flush();//刷新传输流，让写入马上执行，因为RPC调用需要马上得到结果

20 

21 }

 

从上面代码可以看出：首先调用具体一个协议的writeMessageBegin函数，当然这个我们分析的是二进制协议，那就看看二进制协议这个函数的实现，代码如下：

 1 template <class Transport_>

 2 

 3 uint32_t TBinaryProtocolT<Transport_>::writeMessageBegin(const std::string& name,

 4 

 5                                      const TMessageType messageType, const int32_t seqid) {

 6 

 7   if (this->strict_write_) {//判断是否需要强制写入版本号

 8 

 9     int32_t version = (VERSION_1) | ((int32_t)messageType);//本版号是协议号和消息类型的与结果

10 

11     uint32_t wsize = 0;//记录写入的长度

12 

13     wsize += writeI32(version);//写版本号

14 

15     wsize += writeString(name);//写消息名称，这就是函数名称Log

16 

17     wsize += writeI32(seqid);//写调用序列号

18 

19     return wsize;//返回写入的长度

20 

21   } else {

22 

23     uint32_t wsize = 0;

24 

25     wsize += writeString(name);

26 

27     wsize += writeByte((int8_t)messageType);

28 

29     wsize += writeI32(seqid);

30 

31     return wsize;

32 

33   }

34 

35 }

 

根据上面代码和注释可以看出，根据是否需要写入协议版本号写入的内有所差别，写入协议号的目的是可以坚持客户端和服务器端是否使用相同的协议来传输的数据，保证数据格式的正确性。二进制的协议定义如下：

1 static const int32_t VERSION_MASK = 0xffff0000;//取得协议的掩码

2 

3 static const int32_t VERSION_1 = 0x80010000;//具体协议本版号

 

具体写入又调用了自己实现的相应的数据类型写入函数，看看writeString是怎么实现的，如下：

 1 template <class Transport_>

 2 

 3 uint32_t TBinaryProtocolT<Transport_>::writeString(const std::string& str) {

 4 

 5 uint32_t size = str.size();//取得字符串的长度（大小）

 6 

 7   uint32_t result = writeI32((int32_t)size);//写入字符串的长度到服务器

 8 

 9   if (size > 0) {

10 

11       this->trans_->write((uint8_t*)str.data(), size);//调用具体某一个传输方式的写入函数写入字符串数据

12 

13   }

14 

15   return result + size;//返回写入的大小

16 

17 }

 

从上面代码可以看出这些类型的函数就是将对应的数据类型写入服务器，而且具体写入在这里还没有真正的进行，因为后面会讲到的Transport相关类还会对传输方式进行包装。

现在我们继续回到send_Log函数，写入函数调用的消息以后就开始写函数调用需要的参数，函数参数的写入是通过函数参数对应的封装类进行的，Log函数的参数封装类是scribe_Log_pargs，把对应的参数传递给这个类的对象，然后调用它自己的写入函数写入参数到服务器，代码如下：

 1 uint32_t scribe_Log_pargs::write(::apache::thrift::protocol::TProtocol* oprot) const {

 2 

 3 uint32_t xfer = 0;

 4 

 5   xfer += oprot->writeStructBegin("scribe_Log_pargs");//写入参数类的名称

 6 

 7   xfer += oprot->writeFieldBegin("messages", ::apache::thrift::protocol::T_LIST, 1);//写入字段名称和类型

 8 

 9   {

10 

11 //开始写入链表类型

12 

13     xfer += oprot->writeListBegin(::apache::thrift::protocol::T_STRUCT, (*(this->messages)).size());

14 

15     std::vector<LogEntry> ::const_iterator _iter6;

16 

17     for (_iter6 = (*(this->messages)).begin(); _iter6 != (*(this->messages)).end(); ++_iter6)

18 

19     {

20 

21       xfer += (*_iter6).write(oprot);//依次写入链表参数类型里面的每一个

22 

23     }

24 

25     xfer += oprot->writeListEnd();//结束链表类型写入

26 

27 }

28 

29 xfer += oprot->writeFieldEnd();//写入字段结束

30 

31 xfer += oprot->writeFieldStop();//停止写入字段

32 

33 xfer += oprot->writeStructEnd();//写入参数结束

34 

35 return xfer;

36 

37 }

 

具体参数的写入函数根据参数的类型具体处理并写入到服务器端。这样整个函数调用就做完了，剩下的就是处理写入后的一些善后处理，看具体代码有注释。

当函数调用的消息发送出去以后就开始准备接收函数远程调用的结果（异步调用除外），这里接收Log函数调用返回结果的函数是recv_log，代码如下：

 1 ResultCode scribeClient::recv_Log()

 2 

 3 {

 4 

 5   int32_t rseqid = 0;

 6 

 7   std::string fname;

 8 

 9   ::apache::thrift::protocol::TMessageType mtype;//接收返回消息的类型

10 

11   iprot_->readMessageBegin(fname, mtype, rseqid);//读取返回结果的消息

12 

13   if (mtype == ::apache::thrift::protocol::T_EXCEPTION) {//处理返回消息是异常的情况

14 

15     ::apache::thrift::TApplicationException x;

16 

17     x.read(iprot_);//读取异常信息

18 

19     iprot_->readMessageEnd();

20 

21     iprot_->getTransport()->readEnd();

22 

23     throw x;//抛出异常信息

24 

25   }

26 

27   if (mtype != ::apache::thrift::protocol::T_REPLY) {//处理不是正常回复的结果

28 

29     iprot_->skip(::apache::thrift::protocol::T_STRUCT);

30 

31     iprot_->readMessageEnd();

32 

33     iprot_->getTransport()->readEnd();

34 

35   }

36 

37   if (fname.compare("Log") != 0) {//比较是否是Log函数调用返回的结果

38 

39     iprot_->skip(::apache::thrift::protocol::T_STRUCT);

40 

41     iprot_->readMessageEnd();

42 

43     iprot_->getTransport()->readEnd();

44 

45   }

46 

47   ResultCode _return;

48 

49   scribe_Log_presult result;

50 

51   result.success = &_return;

52 

53   result.read(iprot_);//读取结果信息

54 

55   iprot_->readMessageEnd();

56 

57   iprot_->getTransport()->readEnd();

58 

59   if (result.__isset.success) {//成功就正常返回，否则抛出异常信息

60 

61     return _return;

62 

63   }

64 

65   throw ::apache::thrift::TApplicationException(::apache::thrift::TApplicationException::MISSING_RESULT, 

66 

67 "Log failed: unknown result");//抛出不知道结果的异常信息，调用失败了

68 

69 }

 

接收RPC调用结果的函数都是根据返回消息的类型做相应处理，不成功就抛出相应的异常信息。首先这里调用二进制协议的readMessageBegin函数读取由二进制写入的消息（这个当然是服务器端写入的），这个函数代码实现如下：

 1 template <class Transport_>

 2 

 3 uint32_t TBinaryProtocolT<Transport_>::readMessageBegin(std::string& name,

 4 

 5                             TMessageType& messageType, int32_t& seqid) {

 6 

 7   uint32_t result = 0;

 8 

 9   int32_t sz;

10 

11   result += readI32(sz);//读取消息的头部（可能是协议版本号和消息类型的组合，也可能直接是消息）

12 

13   if (sz < 0) {//如果小于0（就是二进制为第一位以1开头，说明是带有协议版本号的

14 

15     // Check for correct version number

16 

17     int32_t version = sz & VERSION_MASK;//取得消息的版本号

18 

19     if (version != VERSION_1) {//如果不匹配二进制协议的版本号就抛出一个坏的协议异常

20 

21       throw TProtocolException(TProtocolException::BAD_VERSION, "Bad version identifier");

22 

23     }

24 

25     messageType = (TMessageType)(sz & 0x000000ff);//取得消息类型

26 

27     result += readString(name);//取得消息名称（也就是函数名称）

28 

29     result += readI32(seqid);//取得函数调用ID号

30 

31   } else {

32 

33     if (this->strict_read_) {//要求读协议本版号，但是这种情况是不存在协议版本号的所以抛出异常

34 

35       throw TProtocolException(TProtocolException::BAD_VERSION,

36 

37  "No version identifier... old protocol client in strict mode?");

38 

39     } else {

40 

41       int8_t type;

42 

43       result += readStringBody(name, sz);//读取消息名称（也就是函数名称）

44 

45       result += readByte(type);//读取消息类型

46 

47       messageType = (TMessageType)type;

48 

49       result += readI32(seqid);//读取函数调用ID号

50 

51     }

52 

53   }

54 

55   return result;//f返回读取数据的长度

56 

57 }

 

上面的函数代码向我们展示了怎样处理基于二进制协议消息的读取和处理的过程，当然这个过程必须是建立在相应的写入消息的过程，只有按照相应的格式才能正确的处理。还有一点需要强调一下，就是每一种数据类型的写入和读取函数也是相对应的，在这里我没有具体分析每一个数据类型的写入函数了，其实也没有必要，也是这些代码都是很容易的，关键是读和写必须配合起来。

到此一个完整的基于二进制协议的RPC调用分析完毕，下面对这个二进制协议进行一下简单的总结。

（1）如果需要传输协议版本号，那么0-4字节就是协议版本号和消息类型；否则0-4字节就直接是消息名称（其实就是函数的名称）的长度，假设长度为len。

（2）如果0-4字节是协议版本号和消息类型，那么5-8字节就是消息名称的长度，同样假设长度为len，然后再跟着len字节的消息名称；否则就是len字节的消息名称。

（3）接下来如果没有带协议版本号的还有1字节的消息类型；

（4）然后都是4字节的请求的序列号；

（5）接着继续写入参数类型的结构体（但是二进制协议并没有真正写入，所以没有占用字节）；

（6）如果真正的有参数的话就继续一次为每一个参数写入1字节的参数类型（在前面已经给出了参数类型的定义，就是一个枚举）、2字节的参数序号和具体参数需要的长度；

（7）具体参数长度的需求如下：

a) 对于以下具有固定长度的简单数据类型的参数：

简单数据类型	长度（字节）	备注
T_STOP       = 0	1
T_VOID       = 1,	1
T_BOOL       = 2	1
T_BYTE       = 3	1
T_I08         = 3	1
T_I16         = 6	2
T_I32         = 8	4
T_U64        = 9	8	二进制协议没有实现
T_I64        = 10	8
T_DOUBLE     = 4	8

b) 复合数据类型：

 

复合数据类型	长度说明
T_STRING = 11	前面4个字节：字符串的长度stringLen； 接下来的stringLen个字节：字符串的内容
T_STRUCT = 12	假设这个结构体包含m个字段：(为了便于说明问题，下面所说的字节偏移是相对于struct内部结构而言的)； 0-1字节：字段的数据类型； 1-3字节：字段序号，取决于你定义的idl文件中参数所定义的序号； 接下来的k个字节：看简单数据类型； 以此类推，直至m个字段。其实，struct的字段和函数参数具有一样的编码方式
T_MAP  = 13	(为了便于说明问题，下面所说的字节偏移是相对于map内部结构而言的)： 0-1字节：key的数据类型。注意，可能是复合数据类型； 1-2字节：value的数据类型。 假设key的数据类型的长度为k个字节，value的数据类型的长度为v个字节，那么接下来每k+v个字节作为一个key-value值，至于key的值的分析和value的值的分析，看简单数据类型
T_SET    = 14	(为了便于说明问题，下面所说的字节偏移是相对于set内部结构而言的)： 0-1字节：set里面的元素的数据类型； 1-5字节：元素个数； 假设元素的数据类型的长度为k个字节，那么接下来每k个字节作为一个元素值，至于元素值的分析，看简单数据类型； 注意，这里和函数参数/struct的区别在于，这里不存在元素的序号值
T_LIST    = 15	和set类似，这里就不重复累赘了。