TcaplusDB PB表 Go 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. 下载Go SDK

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

7. 配置编译开发环境

备注:

• protoc下载后，直接拷贝到/usr/bin目录

• protoc-gen-go下载后，进入相应目录，直接go build -o protoc-gen-go main.go，可得到二进制文件，把其拷贝到/usr/bin系统目录

7.1 PB表proto文件转为go代码

# 将用户定义的mytable.proto文件已经依赖的tcaplusservice.optionv1.proto放在当前目录
mkdir tcaplusservice
#生成pb协议接口代码
protoc --go_out=./tcaplusservice tcaplusservice.optionv1.proto
#生成表定义接口代码
protoc --go_out=./tcaplusservice mytable.proto

备注：

• 需要同时安装protoc-gen-go插件才行

• 需要在proto文件中指定package, 如默认的package tcaplusservice

7.2 编译

进入example目录 按照如下方式build相应的go代码示例即可

# Go parameters
export GO111MODULE=on
export GOPATH:=${GOPATH}:$(shell pwd)/../../../../
GOCMD=go
GOBUILD=$(GOCMD) build
GOCLEAN=$(GOCMD) clean
BINARY_NAME=async

all: build
build:
    $(GOBUILD) -o $(BINARY_NAME) *.go
clean:
    $(GOCLEAN)
    rm -f $(BINARY_NAME)

example目录说明：

• sync 是同步+多协程使用示例（推荐）

• sync2.0 基于sync做了进一步优化封装，同步+option的方式，使用更简单（推荐）

• async 是异步方式使用示例

8. 使用Go SDK

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

9. 常见问题

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

1. 常见问题文档；

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