基础通信协议 Tars
目录
1. Tars 语言
1.1. 接口文件
Tars 语言是一种类 c++标识符的语言,用于生成具体的服务接口文件
Tars 文件是 Tars 框架中客户端和服务端的通信接口,通过 Tars 的映射实现远程对象调用
Tars 文件的扩展名必须以.tars 为扩展名
对于结构定义,可以支持扩展字段,即可以增加字段而不影响原有结构的解析,可以在存储/协议等地方单独使用
大小写敏感
1.2. 词法规则
1.2.1. 注释
采用 c++的注释规范。
1.2.2. 关键字
1.2.3. 标识符
所有标识符不能带有'tars_’符号,且必须以字母开头,同时不能和关键字冲突。
1.3. 基本类型
支持的基本类型包括以下:
void :只能在函数的返回值表示
bool :布尔类型,映射到 tars::Bool
byte :有符号字符,映射到 tars::Char
short :有符号短整型,映射到 tars::Short
int :有符号整型,映射到 tars::Int32
long :有符号长整型,映射到 tars::Int64
float :映射到 tars::Float
double :映射到 tars::Double
string :映射到 std::string,java:String
unsigned byte :无符号字符,c++映射到 unsigend char 其它版本 tars::Short
unsigned short:无符号短整形 c++映射到 unsigned short 其它版本 tars::Int32
Unsigned int:无符号整形 c++映射到 unsigned int 其它版本 tars::Int64
1.4. 复杂类型
1.4.1. 枚举
枚举类型的定义如下:
说明:
枚举类型支持在指定枚举变量的值,例如支持:E1 = 1 这种定义方式;
第一个定义的枚举类型值为 0,这里 E1 的值为 0;
枚举类型在 tars 文件定义后,通过 tars2cpp 生成以后,除了会生成相应的 enum 定义之外,会生成 etos 和 stoe 函数,将枚举值转换成字符串,以及将字符串转换成枚举值,在代码调试时会非常方便。
建议在 c++的 tars 文件中,所有接口都以 int 返回,且返回值在 tars 文件中以枚举来定义。
1.4.2. 常量
Tars 文件中可以定义常量,例如:
说明:
由于 map,vector 没有描述常量的值,因此不支持 map,vector 的定义;
1.4.3. 结构
结构定义如下:
说明:
第一列数字表示该字段的标识(tag),无论结构增减字段,该字段的值都不变,必须和相应的字段对应;
Tag 的值必须要>=0 且<=255;
require 表示该字段必选;
optional 表示该字段可选;
对于 optional 字段,可以有一个缺省值,缺省值在编码时默认不打包;
key 说明:
表示结构的小于比较符号,缺省时 Struct 是没有小于操作的,如果定义了 key,则生成小于比较符。
key 详细说明:
key[Struct, member…]:
Struct:表示结构的名称
Member:表示该结构的成员变量,可以有多个;
生成的小于比较操作符,按照 key 中成员变量定义的顺序进行优先<比较;
生成小于比较操作符以后,该结构就可以作为 map 的 key;
其他说明:
在 Tars 的 c++语言中,对于结构而言,提供两个成员函数用于直接打印出结构的内容,可以用于调试和记录日志:
ostream& display(ostream& _os, int _level=0):直接打印结构的详细内容,主要用于调试;
ostream& displaySimple(ostream& _os, int _level=0):所有成员变量自动按照顺序以|分隔打印出来,用于记录日志;
1.4.4. 序列
序列用 vector 来定义,如下:
1.4.5. 字典
字典用 map 来定义,如下:
说明:
对于 struct,通常不能作为 map 的 key,因此 struct 没有大小比较符号;
如果需要 struct 能够作为 map 的 key,需要用 less 定义 struct 中成员的比较顺序;
1.4.7 嵌套
任何 struct,map,vector 都可以嵌套;
1.5. 接口
接口定义如下,例如:
说明:
表示输出参数
接口定义后,通过自动代码生成工具 (如:tars2cpp)会生成同步接口和异步接口等代码
1.6. 名字空间
所有的 struct,interface 必须在名字空间中,例如:
说明:
名字空间不能嵌套;
可以引用其他名字空间,例如:Demo1::Key
1.7. 引用
一个 tars 文件可以 include 另外一个 tars 文件, 只需要在头部如下引用其他文件即可: #include "other.tars"
即可引用其他 tars 文件中的结构体了
2. Tars 协议
2.1. 数据编码
2.1.1. 基本结构
每一个数据由两个部分组成,如下图:
而其中头信息包括以下几个部分:
Tag 2 是可选的,当 Tag 的值不超过 14 时,只需要用 Tag 1 就可以表示;当 Tag 的值超过 14 而小于 256 时,Tag 1 固定为 15,而用 Tag 2 表示 Tag 的值。Tag 不允许大于 255。
Type 表示类型,用 4 个二进制位表示,取值范围是 0~15,用来标识该数据的类型。不同类型的数据,其后紧跟着的实际数据的长度和格式都是不一样的,详见一下的类型表。
Tag 由 Tag 1 和 Tag 2 一起表示。取值范围是 0~255,即该数据在结构中的字段 ID,用来区分不同的字段。
2.1.2. 编码类型表
注意,这里的类型与 tars 文件定义的类型是两个不同的概念,这里的类型只是标识数据存储的类型,而不是数据定义的类型。
0
int1
紧跟 1 个字节整型数据
1
int2
紧跟 2 个字节整型数据
2
int4
紧跟 4 个字节整型数据
3
int8
紧跟 8 个字节整型数据
4
float
紧跟 4 个字节浮点型数据
5
double
紧跟 8 个字节浮点型数据
6
String1
紧跟 1 个字节长度,再跟内容
7
String4
紧跟 4 个字节长度,再跟内容
8
Map
紧跟一个整型数据表示 Map 的大小,再跟[key, value]对列表
9
List
紧跟一个整型数据表示 List 的大小,再跟元素列表
10
自定义结构开始
自定义结构开始标志
11
自定义结构结束
自定义结构结束标志,Tag 为 0
12
数字 0
表示数字 0,后面不跟数据
13
SimpleList
简单列表(目前用在 byte 数组),紧跟一个类型字段(目前只支持 byte),紧跟一个整型数据表示长度,再跟 byte 数据
2.1.3. 各类型详细描述
1.基本类型(包括 int1、int2、int4、int8、float、double)
头信息后紧跟数值数据。char、bool 也被看作整型。所有的整型数据之间不做区分,也就是说一个 short 的值可以赋值给一个 int。
2.数字 0
头信息后不跟数据,表示数值 0。所有基本类型的 0 值都可以这样来表示。
这是考虑到数字 0 出现的概率比较大,所以单独提一个类型,以节省空间。
3.字符串(包括 String1、String4)
String1 跟一个字节的长度(该长度数据不包括头信息),接着紧跟内容。
String4 与之类似。
4.Map
紧跟一个整形数据(包括头信息)表示 Map 的大小,然后紧跟[Key 数据(Tag 为 0),Value 数据(Tag 为 1)]对列表。
5.List
紧跟一个整形数据(包括头信息)表示 List 的大小,然后紧跟元素列表(Tag 为 0)
6.自定义结构开始
自定义结构开始标志,后面紧跟字段数据,字段按照 tag 升序顺序排列
7.自定义结构结束
自定义结构结束标志,Tag 为 0
2.1.4 对象持久化
对于自定义结构的持久化,由开始标志与结束标志来标识。
比如如下结构定义:
其中,默认的 TestInfo2 结构编码后结果为:
2.2. 消息格式
TUP 底层协议完全采用 Tars 定义,与 Tars 的底层数据包定义一致,其中 require 的字段为 TUP 必须的字段,optional 为访问 Tars 服务时额外需要用到的字段。
2.2.1. 请求包
2.2.2. 响应包
Last updated