tencent cloud

游戏数据库 TcaplusDB

Protobuf 表定义

下载
聚焦模式
字号
最后更新时间: 2024-12-04 09:56:32
TcaplusDB 支持2种表定义格式,protobuf(Protocol Buffers)表 TDR(Tencent Data Representation)表。 Protobuf 是 Google 开发的一种描述性语言,针对结构化数据进行序列化,同时强调数据结构的简单化和性能。 TDR 是由腾讯开发的跨平台数据表示语言,结合了 XML,二进制和 ORM(对象关系映射)的优势,在腾讯游戏数据的序列化场景中广泛使用。 两者在使用上没有根本性的变化,请根据具体业务使用习惯选择表定义语言。 本文主要描述 Protobuf 表定义语言的定义形式。

ProtoBuf 表

TcaplusDB 创建表,首先需要使用表描述语言定义表的格式。将表格定义内容写入文件中,此文件被称之为表的 IDL 描述文件。 ProtoBuf 表的 IDL 描述文件根据 Protocol Buffers 的规则来进行表格定义。 主要分为以下3类定义:
文件定义信息
表定义信息
嵌套类型信息

文件定义信息

文件定义信息区域主要定义当前表描述文件的公共信息。主要涉及3种类型的内容。
选项名称
功能说明
值示例
必填
syntax
指明当前文件书写的语法规范版本
支持 proto2,proto3
是
package
指明当前文件自定义包名,包名可以避免对 message 类型之间的名字冲突。
包名信息
是
import
引入 Tcaplus 表的一些公共信息,必须在您的表定义中被引用
tcaplusservice.optionv1.proto
是

表定义信息

表定义信息主要通过 message 定义表的格式,在 message 种可对表的扩展信息进行定义,也可以对表的字段信息进行定义。

扩展信息定义

同时也可以在 protobuf 语法基础上通过 option 进行扩展,可以实现更丰富的语义功能,可定义的内容如下表所示。 详细的定义格式为:option(tcaplusservice.选项) = "值";
选项名称
功能说明
设置示例
必填
tcaplus_primary_key
设置 TcaplusDB 表主键字段
option(tcaplusservice.tcaplus_primary_key) = "uin,name,region";
是
tcaplus_index
设置 TcaplusDB 表索引键字段
option(tcaplusservice.tcaplus_index) = "index_1(uin,region)";
否
tcaplus_sharding_key
用户可以自定义表分片键
option(tcaplusservice.tcaplus_sharding_key) = "uin";
否
tcaplus_field_cipher_suite
如果需要使用字段加密功能,需要设置,如果用户需要指定自己的加密算法,请参考 API 中的例子
option(tcaplusservice.tcaplus_field_cipher_suite) = "DefaultAesCipherSuite";
否
tcaplus_cipher_md5
如果需要使用字段加密功能,需要设置用户侧保存加密密码字符串的 MD5
option(tcaplusservice.tcaplus_cipher_md5)= "62fee3b53619b7f303c939964c6f2c4b";
否

字段信息定义

TcaplusDB 定义字段的格式为:字段修饰符 字段类型 字段名称 = 标识号[特殊定义];
字段修饰符
proto2 支持3种类型的限定修饰符,proto3可不再支持 required 修饰,默认为 optional 类型。
required:表示字段为必填字段。proto2中主键字段必须被 required 修饰。
optional:表示此字段为可选字段,支持设定字段的默认值
repeated :表示该字段可以包含0~N 个元素。其特性和 optional 一样,但是每一次可以包含多个值。可以看作是在传递一个数组的值,必须指定[packed = true]的特殊定义。
字段类型
TcaplusDB 支持普通字段以及嵌套型字段,详细的字段介绍可参考字段类型
字段名称
针对当前属性而进行对字段进行命名,支持大小写字母,数字与下划线。建议字段的命名采用驼峰式命名方式,不能以数字开头。
标识号
标识号使用范围:[1,2^29 - 1] 不可使用 [19000-19999] 标识号, 因为 Protobuf 协议实现中对这些标识号进行了预留。假若使用,则会报错 每个字段在进行编码时都会占用内存,而 占用内存大小 取决于 标识号:
范围 [1,15] 标识号的字段 在编码时占用1个字节;
范围 [16,2047] 标识号的字段 在编码时占用2个字节
特殊定义
当 repeated 修饰的字段需要指定 packed=true 选项。用法如下:
repeated int64 lockid = 6 [packed = true];
使用 optional 修饰的字段可以通过 default = 1指定其默认值。用法如下:
optional int32 logintime = 5 [default = 1];
字段类型为 string 和 bytes 类型的字段可以指定为加密字段。用法如下:
required string name = 2[(tcaplusservice.tcaplus_crypto) = true];

嵌套类型信息

TcaplusDB 支持嵌套类型,嵌套类型可以包含另一个嵌套类型作为其字段。也可以在嵌套类型内定义一个新的嵌套类型。 嵌套类型的定义与表的定义相似,均是通过 message 进行声明,但是结构体中不能包含扩展信息定义,如“主键”,“索引”等定义。 TcaplusDB 支持最多128层连续嵌套,但是不建议大量使用嵌套,嵌套层数过多会导致数据访问性能降低。

proto2 表描述文件示例

以下是一个符合 proto2 语法规范的表描述文件。
syntax = "proto2"; // 指明符合proto2语法规范
package myTcaplusTable; // 自定义包名

import "tcaplusservice.optionv1.proto"; // 这个文件定义了Tcaplus表的一些公共信息,需要在您的表定义中被引用(import)

message player { //使用message定义表,message名即表名

// 必须是指定了主键选项(tcaplusservice.tcaplus_primary_key)的message才能被识别为一张TcaplusDB业务数据表,否则此message只是一个结构体
// 主键选项指定了主键字段名列表,字段名用逗号分割,最多四个字段能够被指定为主键
option(tcaplusservice.tcaplus_primary_key) = "uin,name,region";

// tcaplusservice.tcaplus_index选项指定Tcaplus索引
// 每个索引所包含的索引键必须是主键,并且所有索引字段集合的交集不能为空
option(tcaplusservice.tcaplus_index) = "index_1(uin,region)";
option(tcaplusservice.tcaplus_index) = "index_2(uin,name)";

//option(tcaplusservice.tcaplus_sharding_key) = "uin"; 用户可以自己显式设置索引分片字段。如果用户不显式设置,那系统将默认采用主键字段作为分片字段。

option(tcaplusservice.tcaplus_field_cipher_suite) = "DefaultAesCipherSuite"; // 使用默认的DefaultAesCipherSuite加密函数,非必须设置选项。
option(tcaplusservice.tcaplus_cipher_md5)= "62fee3b53619b7f303c939964c6f2c4b"; //设置加密密码字符串的md5值,非必须设置选项。

// 接下来是表的字段定义
// TcaplusDB 表支持以下的数据类型:
// 非嵌套类型:int32, int64, uint32, uint64, sint32, sint64, bool, fixed64, sfixed64, double, fixed32, sfixed32, float, string, bytes
// 嵌套类型:message
// Tcaplus支持REQUIRED, OPTIONAL和REPEATED作为字段修饰符

// 主键字段 (最多4个)
required int64 uin = 1; // 主键字段必须被required类型修饰,并且不能是嵌套类型
required string name = 2[(tcaplusservice.tcaplus_crypto) = true]; //message中string和bytes类型的字段可以指定为加密字段,非必须设置选项
required int32 region = 3;
// 一张表最多只能包含4个主键字段

// 普通值字段
required int32 gamesvrid = 4; // 普通字段可以被required,optional或repeated类型修饰
optional int32 logintime = 5 [default = 1];
repeated int64 lockid = 6 [packed = true]; // repeated修饰的字段需要指定packed=true选项
optional bool is_available = 7 [default = false]; //optional类型字段可以指定默认值
optional pay_info pay = 8; // 值字段的类型可以是自定义的结构体类型
}

message pay_info { //使用message定义结构体

required int64 pay_id = 1;
optional uint64 total_money = 2;
optional uint64 pay_times = 3;
optional pay_auth_info auth = 4;

message pay_auth_info { // 结构体类型支持嵌套定义
required string pay_keys = 1;
optional int64 update_time = 2;
}
}

proto3 表描述文件示例

以下是一个符合 proto3 语法规范的表描述文件。
syntax = "proto3"; // 指明符合proto3语法规范
package myTcaplusTable; // 自定义包名

import "tcaplusservice.optionv1.proto"; // 这个文件定义了Tcaplus表的一些公共信息,需要在您的表定义中被引用(import)

message player { //使用message定义表,message名即表名

// 必须是指定了主键选项(tcaplusservice.tcaplus_primary_key)的message才能被识别为一张TcaplusDB业务数据表,否则此message只是一个结构体
// 主键选项指定了主键字段名列表,字段名用逗号分割,最多四个字段能够被指定为主键
option(tcaplusservice.tcaplus_primary_key) = "uin,name,region";

// tcaplusservice.tcaplus_index选项指定Tcaplus索引
// 每个索引所包含的索引键必须是主键,并且所有索引字段集合的交集不能为空
option(tcaplusservice.tcaplus_index) = "index_1(uin,region)";
option(tcaplusservice.tcaplus_index) = "index_2(uin,name)";

//option(tcaplusservice.tcaplus_sharding_key) = "uin"; 用户可以自己显式设置分片字段,如果用户不显式设置,那系统将默认采用主键字段为分片字段。

option(tcaplusservice.tcaplus_field_cipher_suite) = "DefaultAesCipherSuite"; // 使用默认的DefaultAesCipherSuite加密函数,非必须设置选项
option(tcaplusservice.tcaplus_cipher_md5)= "62fee3b53619b7f303c939964c6f2c4b"; //设置加密密码字符串的md5值,非必须设置选项

// 接下来是表的字段定义
// Tcaplus 表支持以下的数据类型:
// 非嵌套类型:int32, int64, uint32, uint64, sint32, sint64, bool, fixed64, sfixed64, double, fixed32, sfixed32, float, string, bytes
// 嵌套类型:message

// 主键字段 (最多4个)
int64 uin = 1; // 主键字段必须是非嵌套类型
string name = 2[(tcaplusservice.tcaplus_crypto) = true]; //message中string和bytes类型的字段可以指定为加密字段,非必须设置选项
int32 region = 3;
// 一张表最多只能包含4个主键字段

// 普通值字段
int32 gamesvrid = 4;
int32 logintime = 5;
int64 lockid = 6;
bool is_available = 7;
pay_info pay = 8; // 值字段的类型可以是自定义的结构体类型
}

message pay_info { //使用message定义结构体

int64 pay_id = 1;
uint64 total_money = 2;
uint64 pay_times = 3;
pay_auth_info auth = 4;

message pay_auth_info { // 结构体类型支持嵌套定义
string pay_keys = 1;
int64 update_time = 2;
}
}


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈