【TARS】TARS协议的编解码

目录

 

0.现有编解码方式

1.编解码

2.TARS底层协议

3.TUP

3.1TUP是什么

3.2TUP能做什么

3.3TUP不能做什么

3.4依赖和约束 

4.TARS协议的序列化与反序列化调用的函数

5.源码分布

6.协议序列化分析(以响应报文为例)

6.0如何进行序列化

6.1响应包体

6.2响应包体中每个成员变量的序列化后的组成部分HEAD+BUF

6.3分析HEAD

6.3.1HEAD的组成

6.3.2TAG的取值逻辑

6.3.3 TYPE的取值范围与取值逻辑

7.响应协议反序列化

7.1理解反序列化

7.2路小饭的协议反序列化测试示例

8.我自己写的测试序列化和反序列化的测试程序及逻辑说明

 

 

---

 

0.现有编解码方式

序列化与反序列化编码原理--阅读链接--感谢作者！

1.编解码

引用阅读

官方引用阅读-02-关于协议,Tars文件以及翻译工具tars2node的说明

宝藏文章！

统一通信协议 TarsTup

宝藏路小饭

路小饭对于TARS的编解码的讲解

路小饭对TARS的编解码的测试用例

编码-序列化
解码-反序列化

序列化：将对象变为二进制内容，写入到IO流中；
反序列化：从IO流获取到二进制内容，将其恢复为对象.

tars序列化过程：TARS编码协议是一种数据编解码规则，它将整形、枚举值、字符串、序列、字典、自定义结构
体等数据类型按照一定的规则编码到二进制数据流中。对端接收到二进制数据流之后，按照相应的规则反序列化
可得到原始数值。简单理解，TARS编码协议提供了一种将数据序列化、反序列化的方法。其角色和我们认识的
protobuf、json、xml等同.

2.TARS底层协议

Tars服务之间通讯的底层协议格式, 具体参见RequestF.tars & BaseF.tars.

RequestPacket和ResponsePacket 是两个Tars服务通信的底层协议, 简单的说如果不通过Tars的
Communicator来通信, 你可以自己组包来完成和Tars服务的通信(当然这会有相当的难度, 需要你
对Tars底层协议非常熟悉), 因此为了方便TUP构建出来解决这种问题.


module tars
{
    //请求包体
    struct RequestPacket
    {
        1  require short        iVersion;
        2  require byte         cPacketType  = 0;
        3  require int          iMessageType = 0;
        4  require int          iRequestId;
        5  require string       sServantName = "";
        6  require string       sFuncName    = "";
        7  require vector sBuffer;
        8  require int          iTimeout     = 0;
        9  require map context;
        10 require map status;
    };

    //响应包体
    struct ResponsePacket
    {
        1 require short         iVersion;
        2 require byte          cPacketType  = 0;
        3 require int           iRequestId;
        4 require int           iMessageType = 0;
        5 require int           iRet         = 0;
        6 require vector  sBuffer;
        7 require map status;
        8 optional string        sResultDesc;
        9 optional map context;
    };
};

module tars
{
    
    // 定义协议的版本号

    const short TARSVERSION  = 0x01;
    const short TUPVERSION  = 0x03;

    
    // 定义消息的类型

    // 普通调用
    const byte TARSNORMAL  = 0x00;

    // 单向调用
    const byte TARSONEWAY  = 0x01;

    
    // TARS定义的返回码

    const int TARSSERVERSUCCESS       = 0;       //服务器端处理成功
    const int TARSSERVERDECODEERR     = -1;      //服务器端解码异常
    const int TARSSERVERENCODEERR     = -2;      //服务器端编码异常
    const int TARSSERVERNOFUNCERR     = -3;      //服务器端没有该函数
    const int TARSSERVERNOSERVANTERR  = -4;      //服务器端没有该Servant对象
    const int TARSSERVERRESETGRID     = -5;      //服务器端灰度状态不一致
    const int TARSSERVERQUEUETIMEOUT  = -6;      //服务器队列超过限制
    const int TARSASYNCCALLTIMEOUT    = -7;      //异步调用超时
    const int TARSINVOKETIMEOUT       = -7;      //调用超时
    const int TARSPROXYCONNECTERR     = -8;      //proxy链接异常
    const int TARSSERVEROVERLOAD      = -9;      //服务器端超负载,超过队列长度
    const int TARSADAPTERNULL         = -10;     //客户端选路为空，服务不存在或者所有服务down掉了
    const int TARSINVOKEBYINVALIDESET = -11;     //客户端按set规则调用非法
    const int TARSCLIENTDECODEERR     = -12;     //客户端解码异常
    const int TARSSERVERUNKNOWNERR    = -99;     //服务器端位置异常

    /
    // 定义按位的消息状态类型,可复合

    const int TARSMESSAGETYPENULL     = 0x00;    //无状态
    const int TARSMESSAGETYPEHASH     = 0x01;    //HASH消息
    const int TARSMESSAGETYPEGRID     = 0x02;    //灰度消息
    const int TARSMESSAGETYPEDYED     = 0x04;    //染色消息
    const int TARSMESSAGETYPESAMPLE   = 0x08;    //stat采样消息
    const int TARSMESSAGETYPEASYNC    = 0x10;    //异步调用程序
    //const int TARSMESSAGETYPELOADED = 0x20;    //按负载值调用程序
    //const int TARSMESSAGETYPESETED = 0x40;     //按set规则调用类型，此字段后面将不使用
    const int TARSMESSAGETYPESETNAME = 0x80;     //按setname规则调用类型
    const int TARSMESSAGETYPETRACK   = 0x100;    //track调用链消息
    /
}

3.TUP

3.1TUP是什么

TUP（Tars Uni-Protocol的简称），Tars统一协议，是基于Tars编码的命令字（Command）层协议的封装。
它的存在最早是为了方便各语言客户端调用Tars服务, 只提供了编解码, 网路通讯需要自己实现, 当然如果
Tars提供了这个语言的客户端, 那么就不需要再使用TUP协议来调用Tars服务了.


在正式使用中, 我们有这种场景, 以供大家参考:

(1)后端服务使用Tars服务实现;
(2)实现一个HTTP+TUP协议的全异步代理, 即入口是HTTP+TUP, 出口是TARS协议的代理;
(3)Android/Ios通过TUP协议, 并通过这个代理服务, 完成和后台任何Tars服务的通信.

3.2TUP能做什么

1.支持java、c++等语言；

2.支持对象的序列化和反序列化；

3.支持协议动态扩展；

4.提供put/get泛型接口，快速实现客户端/服务端的编解码；

5.支持直接调用Tars的服务端.

3.3TUP不能做什么

1.只做协议封装，不包含网络层;

2.不支持数据压缩（可在业务层处理）;

3.不支持加密协议（可在业务层处理）.

3.4依赖和约束 

1.依赖Tars协议，TUP用到的结构体对象必须通过Tars定义后生成；
2.依赖各个语言的代码生成工具，如：tars2cpp/tars2java等；
3.TarsUniPacket中封装的Tars相关的接口（如getTars.../setTars...），只有在调用Tars服务是需要用到
4.使用过程中，使用UniPacket完成请求与相应的数据传递，其中ServantName（服务对象名） 与FuncName
（接口名）为必须设定的参数，否则编码失败
5.不建议get/put太多数据，如果有比较多数据，建议在tars文件中组成一个struct，然后put/get到
UniPacket中，便于提高效率和减少网络包大小；
6.UniPacket编码后的结果在包头包含了4个字节网络字节序的包长信息，长度包括包头，接收方收到包后需根据
包头的内容，判断包长，确保包完整后，传入解码接口进行解码（无需去掉包头）；
7.Tars c++语言的string 类型接口建议不要包含二进制数据，二进制数据用vector传输.

4.TARS协议的序列化与反序列化调用的函数

序列化数据使用的是：  ResponsePacket.writeTo()
反序列化数据使用的是：ResponsePacket.readFrom()
代码路径：D:\005-02-代码\016-TARS\TARS\TarsFramework\tarscpp\servant\tup\RequestF.h
struct RequestPacket
{
  ...

        template
        void writeTo(tars::TarsOutputStream& _os) const
        {
            _os.write(iVersion, 1);
            _os.write(cPacketType, 2);
            _os.write(iMessageType, 3);
            _os.write(iRequestId, 4);
            _os.write(sServantName, 5);
            _os.write(sFuncName, 6);
            _os.write(sBuffer, 7);
            _os.write(iTimeout, 8);
            _os.write(context, 9);
            _os.write(status, 10);
        }
        template
        void readFrom(tars::TarsInputStream& _is)
        {
            resetDefautlt();
            _is.read(iVersion, 1, true);
            _is.read(cPacketType, 2, true);
            _is.read(iMessageType, 3, true);
            _is.read(iRequestId, 4, true);
            _is.read(sServantName, 5, true);
            _is.read(sFuncName, 6, true);
            _is.read(sBuffer, 7, true);
            _is.read(iTimeout, 8, true);
            _is.read(context, 9, true);
            _is.read(status, 10, true);
        }
...
}


 struct ResponsePacket {
...
        template
        void writeTo(tars::TarsOutputStream& _os) const
        {
            _os.write(iVersion, 1);
            _os.write(cPacketType, 2);
            _os.write(iRequestId, 3);
            _os.write(iMessageType, 4);
            _os.write(iRet, 5);
            _os.write(sBuffer, 6);
            _os.write(status, 7);
            if (sResultDesc != "")
            {
                _os.write(sResultDesc, 8);
            }
            if (context.size() > 0)
            {
                _os.write(context, 9);
            }
        }
        template
        void readFrom(tars::TarsInputStream& _is)
        {
            resetDefautlt();
            _is.read(iVersion, 1, true);
            _is.read(cPacketType, 2, true);
            _is.read(iRequestId, 3, true);
            _is.read(iMessageType, 4, true);
            _is.read(iRet, 5, true);
            _is.read(sBuffer, 6, true);
            _is.read(status, 7, true);
            _is.read(sResultDesc, 8, false);
            _is.read(context, 9, false);
        }




...
}

5.源码分布

D:\005-02-代码\016-TARS\TARS\TarsFramework\tarscpp\servant\tup\tup.h
D:\005-02-代码\016-TARS\TARS\TarsFramework\tarscpp\servant\tup\Tars.h
D:\005-02-代码\016-TARS\TARS\TarsFramework\tarscpp\servant\tup\RequestF.h

6.协议序列化分析(以响应报文为例)

6.0如何进行序列化

把结构化数据序列化，就是想办法把不同类型的数据按照顺序放在一个字符串里,反序列化就是还能从这个字符
串里把类型和数据正确解析出来,一般来说，要达成正确的效果,必须考虑三点：

(1)标记数据的位置,例如是位于字符串头部还是字符串末尾,或者中间某个部分.
(2)标记数据的类型,例如int char float vector等
(3)标记数据内容.

6.1响应包体

struct ResponsePacket
{
        1 require short         iVersion;
        2 require byte          cPacketType  = 0;
        3 require int           iRequestId;
        4 require int           iMessageType = 0;
        5 require int           iRet         = 0;
        6 require vector  sBuffer;
        7 require map status;
        8 optional string        sResultDesc;
        9 optional map context;
};

6.2响应包体中每个成员变量的序列化后的组成部分HEAD+BUF

每个成员变量的数据是由两部分组成：
HEAD + BUF 

HEAD为头部信息（包含了数据位置和数据类型），BUF为实际数据.
注意BUF里可以继续嵌套| HEAD | BUF |这样的类型，以满足复杂数据结构的需要.
像char、short、int之类的简单类型时，只需要：| HEAD | BUF |
当数据类型为vector< char >时，就变为了| HEAD1 | HEAD2 | BUF |,这时候HEAD1 存储vector类型，HEAD2 存储char类型

6.3分析HEAD

6.3.1HEAD的组成

HEAD的构成为：
| TAG1(4 bits) | TYPE(4 bits) | TAG2(1 byte或者8 bits).

D:\005-02-代码\016-TARS\TARS\TarsFramework\tarscpp\servant\tup\RequestF.h
响应报文的序列化源码：        
struct ResponsePacket 
{
        ...
        template // line 204 ,ver 2-14-2
        void writeTo(tars::TarsOutputStream& _os) const
        {
            _os.write(iVersion, 1);
            _os.write(cPacketType, 2);
            _os.write(iRequestId, 3);
            _os.write(iMessageType, 4);
            _os.write(iRet, 5);
            _os.write(sBuffer, 6);
            _os.write(status, 7);
            if (sResultDesc != "")
            {
                _os.write(sResultDesc, 8);
            }
            if (context.size() > 0)
            {
                _os.write(context, 9);
            }
}





write的第一个参数的值是每个变量对应的value值,第二个参数对应的值是每个变量对应的tag值.
要注意每个变量还自己带了一个属性值，就是它的数据类型.

write函数给出了很多重载形式：
如：

 

6.3.2TAG的取值逻辑

#define TarsWriteToHead(os, type, tag) \
do { \
    if (tars_likely((tag) < 15)) \
    { \
        //当tag的值小于15的时候只有TAG1
        TarsWriteUInt8TTypeBuf( os, (type) + ((tag)<<4) , (os)._len); \
    } \
    else \
    { \
        //当tag的值小于15的时候有TAG1还有TAG2
        TarsWriteUInt8TTypeBuf( os, (type) + (240) , (os)._len); \
        TarsWriteUInt8TTypeBuf( os, (tag),  (os)._len);\
    } \
} while(0)


#define TarsWriteUInt8TTypeBuf(os, val, osLen) \
do { \
    TarsReserveBuf(os, (osLen)+sizeof(uint8_t)); \
    (*(uint8_t *)((os)._buf + (osLen))) = (val); \
    (osLen) += sizeof(uint8_t); \
} while(0)


【具体看个TAG小于14的例子：TAG1为1，TYPE为TarsHeadeInt32(2)，用二进制表示的话，TAG1为0001，
TYPE为0010，HEAD组成方式是将TAG1二进制和TYPE二进制拼接起来，即：
00010010 换算为10进制是18。 前4位为TAG1，后4位为TYPE，从这样的拼接方式中可以看到，相当于是把
TAG1右移了4位再加上TYPE
从上面贴出的代码中我们也可以看到拼接方式的表示："(type) + ((tag)<<4)"，即：HEAD = 2 + (1<<4) 
= 2 + 16 = 18。就这样Tars协议可以用1byte同时表示数据类型和数据位置.

再看个TAG大于14的例子：TAG1为240(固定值)，TAG2为200，TYPE为TarsHeadeInt32(2)，HEAD的二进制表示为：
11110010 11001000 用10进制表示为242 200 前八位中，1111代表TAG1的值240（即11110000）,0010代
表TYPE的值2（即0010）。后八位为TAG2的值200（即11001000）
】

6.3.3 TYPE的取值范围与取值逻辑

TYPE表示类型，用4个二进制位表示，取值范围是0~15，用来标识数据类型，也就是下面的值中的一个.
//数据头类型
#define TarsHeadeChar  0        // 0000
#define TarsHeadeShort 1        // 0001
#define TarsHeadeInt32 2        // 0010
#define TarsHeadeInt64 3        // 0011
#define TarsHeadeFloat 4        // 0100
#define TarsHeadeDouble 5       // 0101
#define TarsHeadeString1 6      // 0110
#define TarsHeadeString4 7      // 0111
#define TarsHeadeMap 8          // 1000
#define TarsHeadeList 9         // 1001
#define TarsHeadeStructBegin 10 // 1010
#define TarsHeadeStructEnd 11   // 1011
#define TarsHeadeZeroTag 12     // 1100
#define TarsHeadeSimpleList 13  // 1101


D:\005-02-代码\016-TARS\TARS\TarsFramework\tarscpp\servant\tup\Tars.h
此处版本是2-14-2.从64行开始声明

7.响应协议反序列化

7.1理解反序列化

理解了协议的序列化，反序列化就比较简单了，假设已经知道iVersion的反序列化数据为^P^A，其中|HEAD|为
^P(注意，HEAD只占一个Byte)

^P转为十进制整数为16，转为二进制为00010000
将数据00010000右移4位为00000001，这就是TAG的值1
将数据00010000做与运算：00010000 & 0x0F = 0, 这就是TYPE的值0，即TarsHeadeChar
知道了TYPE的值，后面|BUF|所占长度可由TYPE得到，本例中也占一个字节，及^A，转为十进制整数为1
这样就完成了iVersion的反序列化

7.2路小饭的协议反序列化测试示例

路小饭的文章链接-访问原文可以看到路小饭提供的测试代码-谢谢路小饭啦

路小饭的代码在我的虚拟机上的位置：/home/muten/TARS-MODULE/Luxiaofan/lxf

//learn-tars/tup/main.cpp
 56 //反序列化
 57 
 58     list done;
 59 
 60     ProxyProtocol   _proxyProtocol;
 61 
 62     _proxyProtocol.responseFunc = ProxyProtocol::tarsResponse;
 63 
 64     const char* data = s.c_str();
 65 
 66     size_t len = s.size();
 67 
        //反序列化方法，反序列化完的数据放入done中
 68     size_t pos = _proxyProtocol.responseFunc(data, len, done);


这里的responseExFunc来自ProxyProtocol::tarsResponse，其中最主要的逻辑是
//learn-tars/tup/AppProtocal.h
451                 ResponsePacket rsp;
452                 rsp.readFrom(is);

rsp.readFrom(is)中readFrom的实现代码如下：
//learn-tars/tup/RequestF.h
166         template
167         void readFrom(tars::TarsInputStream& _is)
168         {
169             resetDefautlt();
170             _is.read(iVersion, 1, true);
171             _is.read(cPacketType, 2, true);
172             _is.read(iRequestId, 3, true);
173             _is.read(iMessageType, 4, true);
174             _is.read(iRet, 5, true);
175             _is.read(sBuffer, 6, true);
176             _is.read(status, 7, true);
177             _is.read(sResultDesc, 8, false);
178             _is.read(context, 9, false);
179         }

同样以iVersion为例，简要说明代码处理流程：

上面170行代码会调用：
//learn-tars/tup/Tars.h
1105         void read(Short& n, uint8_t tag, bool isRequire = true)
1106         {
1107             std::cout<<"read Short "<> 4; \
 263     std::cout<<"TarsPeekFromHead tmpTag "<<(int)tmpTag<

8.我自己写的测试序列化和反序列化的测试程序及逻辑说明

代码路径：/home/muten/TARS-MODULE

// 编译的时候加上-std=c++11

#include 
#include 
#include 
#include