TcaplusDB PB表 C++ SDK 开始使用

使用Go SDK的前期准备工作主要包括：

1. 准备环境；
2. 创建业务；
3. 创建游戏区；
4. 创建表格；
5. 收集环境信息；
6. 下载SDK；
7. 配置开发环境。

以上准备工作已经完成，可以直接跳过。

1. 准备环境

参考创建集群文档，部署TcaplusDB集群，或者申请TcaplusDB服务。

2. 创建业务

参考创建业务文档，创建业务（App）。

3. 创建游戏区

参考创建游戏区文档，创建游戏区（Zone）。

4. 创建表格

参考创建表格文档，创建数据表。

PB表分为Generic表和List表两种。 TcaplusDB所有pb表依赖该表 tcaplusservice.optionv1.proto

// TcaplusService option Ver.1
// Author: Calvinshao
// 2016-8-1

syntax = "proto2";

package tcaplusservice;

import "google/protobuf/descriptor.proto";

extend google.protobuf.MessageOptions
{
    optional string tcaplus_primary_key = 60000; //Tcaplus Primary Key
    repeated string tcaplus_index = 60001; //Tcaplus Index
}

extend google.protobuf.FieldOptions
{
    optional uint32 tcaplus_size = 60000; // Tcaplus field size
    optional string tcaplus_desc = 60001; // Tcaplus description
}

4.1. Generic表定义说明

Generic表描述文件内容示例：

syntax = "proto3";         // 指定protobuf语言版本,proto3.

// 导入TcaplusDB公共定义服务 
import "tcaplusservice.optionv1.proto";

message game_players {  // 定义TcaplusDB表，包含message类型

// 基于选择项tcaplusservice.tcaplus_primary_key创建主键字段
// TcaplusDB单个表最多能指定8个主键字段(3.37.0及其之后版本)
    option(tcaplusservice.tcaplus_primary_key) = "player_id, player_name, player_email";
    option(tcaplusservice.tcaplus_sharding_key) = "player_id";

    // 基于选择项tcaplusservice.tcaplus_index创建主键索引
    option(tcaplusservice.tcaplus_index) = "index_1(player_id, player_name)";
    option(tcaplusservice.tcaplus_index) = "index_2(player_id, player_email)";

    // TcaplusDB支持的数值类型:
    // int32, int64, uint32, uint64, sint32, sint64, bool, fixed64, sfixed64, double, fixed32, sfixed32, float, string, bytes
    // 嵌套类型: message

    // 主键字段
    int64 player_id = 1; 
    string player_name = 2;
    string player_email = 3;

    // 普通(非主键) 字段
    int32 game_server_id = 4;
    repeated string login_timestamp = 5;
    repeated string logout_timestamp = 6;
    bool is_online = 7;

    payment pay = 8;
}

message payment {

int64 pay_id = 1;
uint64 amount = 2;
int64 method = 3;

}

PB表描述文件格式说明参见PB表文档。

4.2. List表定义说明

List表描述文件内容示例：

syntax = "proto3";

package myTcaplusTable;

import "tcaplusservice.optionv1.proto";

message tb_online_list {
    option(tcaplusservice.tcaplus_primary_key) = "openid,tconndid,timekey";
    option(tcaplusservice.tcaplus_customattr) = "TableType=LIST;ListNum=1900";

    int32 openid = 1;
    int32 tconndid = 2;
    string timekey = 3;
    string gamesvrid = 4;
    int32 logintime = 5 ;
    repeated int64 lockid = 6;
    pay_info pay = 7;

    message pay_info {
        uint64 total_money = 1;
        uint64 pay_times = 2;
    }
    map<string, pay_info> projects = 8;
}

PB表描述文件格式说明参见PB表文档。

通过表定义的tcaplus_customattr中的TableType=LIST来标识是List表，同样通过ListNum属性来指定，单个List最多可以存放多少个元素。

注意：由于List表会内置一个存放List中元素序号的主键字段，因此对于用户来说，最多只能为List表定义7个主键字段。

5. 收集环境信息

使用SDK时，需要用到一些环境相关参数，具体参数和收集方法见下表。

6. 下载C++ SDK

C++ SDK发布版本说明和下载连接参见PB表SDK下载。

7. 配置编译开发环境

SDK 依赖一些系统库,主要如下:

• autoconf
• automake
• libtool
• curl
• make
• g++
• unzip
• gcc-c++
• openssl
• openssl-devel
• zlib-devel

可通过 yum 一建安装:

yum install -y autoconf automake libtool curl make g++ unzip gcc-c++ openssl openssl-devel zlib-devel

protobuf 安装：

需要下载源码编译安装,或安装已经编译好的 protobuf. 版本要求与SDK保持一致

./configure --prefix=/usr/local/protobuf
make
make check
make install

注:如果编译过程有问题,一般是少系统库问题,可参阅网上资料解决.

安装完后, 可测试是否 ok. 进/usr/local/protocbuf/bin 目录,执行:

./protoc --version
# 显示版本号
libprotoc 3.5.0

7.1 SDK各目录介绍

• include目录 SDK的头文件，使用SDK需要包含相应的头文件，所有的API接口均有注释，可在头文件中查看
• lib目录 SDK静态库目录，编译时需要以静态链接的方式进行链接
• example目录 包含了所有的PB和TDR表的操作示例，参见C++ SDK各接口的使用说明了解详情
• bin目录 存放的是TcaplusDB Client工具，点击链接了解使用方式
• cfg目录 存放的是TcaplusDB Client工具配套使用的，log配置文件

7.2 proto文件转化为C++代码

• PROTOBUF_HOME环境变量：指定安装的protobuf依赖库的路径，请按以下方式正确指定路径

• TCAPLUS_HOME环境变量：下载的PB SDK解压后的路径，请按以下方式正确指定路径

export PROTOBUF_HOME=/usr/local/protobuf;
export TCAPLUS_HOME=/root/TcaplusPbApi3.46.0.199033.x86_64_release_20201210/release/x86_64/;

将proto文件转化为C++代码（示例代码路径：examples/tcaplus/C++_pb2_asyncmode_simpletable/SingleOperation/add/conv.sh）

${PROTOBUF_HOME}/bin/protoc -I${PROTOBUF_HOME}/include/ -I${TCAPLUS_HOME}/include/tcaplus_pb_api/ --cpp_out=./  --proto_path=./ table_test.proto

7.3 编译

每个example下均有makefile文件，使用的PROTOBUF_HOME和TCAPLUS_HOME按7.2方式设置（示例MakeFile路径：examples/tcaplus/C++_pb2_asyncmode_simpletable/SingleOperation/add/Makefile）

# ================================================================
#Makefile for tcaplus example
#
# Date:   2016-09-14
#
# Copyright (C) 2016 Architechure IRED TENCENT
#
# ================================================================

CPPFILE=$(wildcard *.cpp)
CCFILE=$(wildcard *.cc)

#GENERATE_FILE=$(shell ./conv.sh )

LIBS += -L$(PROTOBUF_HOME)/lib/ -L$(TCAPLUS_HOME)/lib -Wl,-Bstatic -ltcaplusprotobufapi -lprotobuf -ltcew -lexpat -Wl,-Bdynamic -lpthread -lz -ldl -lcrypto -lanl

INC =-I$(PROTOBUF_HOME)/include/ -I$(TCAPLUS_HOME)/include/tcaplus_pb_api/ -I../../../C++_common_for_pb


.PHONY: all clean 

all:
        g++ -o mytest $(CCFILE) $(CPPFILE) $(INC) ${LIBS}  

clean:
        rm -f mytest     mytest.log*

8. 使用Go SDK

参见Go SDK各接口的使用说明。

9. 常见问题

使用SDK的过程中，有疑问（如查看SDK版本，配置SDK日志打印，升级SDK等），或者遇到报错，可参考“常见问题”和“错误码含义和处理方法”进行处理。

1. 常见问题文档；

2. 错误码含义和处理方法文档。