【深入理解TcaplusDB技術】TcaplusDB Go SDK手冊（二）
阿新 • • 發佈：2022-04-18
4 介面列表
支援命令：
//Generic表插入請求
TcaplusApiInsertReq = 0x0001
//Generic表替換/插入請求
TcaplusApiReplaceReq = 0x0003
//Generic表增量更新請求
TcaplusApiIncreaseReq = 0x0005
//Generic表單條查詢請求
TcaplusApiGetReq = 0x0007
//Generic表刪除請求
TcaplusApiDeleteReq = 0x0009
//Generic表刪除應答
TcaplusApiDeleteRes = 0x000a
//Generic表更新請求
TcaplusApiUpdateReq = 0x001d
//List表查詢所有元素請求
TcaplusApiListGetAllReq = 0x000b
//Generic表批量查詢請求
TcaplusApiBatchGetReq = 0x0017
//Generic表按索引查詢請求
TcaplusApiGetByPartkeyReq = 0x0019
//Generic表按索引更新請求
TcaplusApiUpdateByPartkeyReq = 0x004d
//Generic表按索引刪除請求
TcaplusApiDeleteByPartkeyReq = 0x004f
4.1 Client介面
4.1.1 建立tcaplus client
/**
@brief 建立一個tcaplus api客戶端
@retval 返回客戶端指標
**/
func NewClient() *Client
4.1.2 日誌配置介面
建立client之後，立刻呼叫
/**
@brief 設定API日誌配置檔案全路徑log.conf(json格式，example下有示例)，請在client.Dial之前呼叫
@param [IN] cfgPath 日誌配置檔案全路徑log.conf
@retval 錯誤碼
@note Api日誌預設使用的zap，使用者也可自行實現日誌介面logger.LogInterface，呼叫SetLogger進行設定
**/
func (c *Client) SetLogCfg(cfgPath string) error
/**
@brief 自定義API日誌介面,使用者實現logger.LogInterface日誌介面，日誌將列印到使用者的日誌介面中，請在client.Dial之前呼叫
@param [IN] handle logger.LogInterface型別的日誌介面
@retval 錯誤碼
**/
func (c *Client) SetLogger(handle logger.LogInterface)
4.1.3 連線tcaplus介面
/**
@brief 連線tcaplue函式
@param [IN] appId appId，在網站註冊相應服務以後，你可以得到該appId
@param [IN] zoneList 需要操作表的區服ID列表，操作的表在多個不同的zone，填zoneId列表；操作的表在一個zone，zone列表填一個zoneId
@param [IN] signature 簽名/密碼，在網站註冊相應服務以後，你可以得到該字串
@param [IN] dirUrl 目錄伺服器的url，形如"tcp://172.25.40.181:10600"
@param [IN] timeout second, 連線所有表對應的tcaplus proxy伺服器。若所有的proxy連通且鑑權通過，則立即返回成功；
若到達超時時間，只要有一個proxy連通且鑑權通過，也會返回成功；否則返回超時錯誤。
@retval 錯誤碼
**/
func (c *Client) Dial(appId uint64, zoneList []uint32, dirUrl string, signature string, timeout uint32) error
4.1.4 建立tcaplus請求
/**
@brief 建立指定分割槽指定表的tcaplus請求
@param [IN] zoneId 區服ID
@param [IN] tableName 表名
@param [IN] cmd 命令字(cmd包中cmd.TcaplusApiGetReq等)
@retval request.TcaplusRequest tcaplus請求
@retval error 錯誤碼
*/
func (c *Client) NewRequest(zoneId uint32, tableName string, cmd int) (request.TcaplusRequest, error)
4.1.5 傳送tcaplus請求
/**
@brief 傳送tcaplus請求
@param [IN] req tcaplus請求
@retval error 錯誤碼
*/
func (c *Client) SendRequest(req request.TcaplusRequest) error
4.1.6 非同步接收tcaplus響應
/**
@brief 非同步接收tcaplus響應
@retval response.TcaplusResponse tcaplus響應
@retval error 錯誤碼
error nil，response nil 成功但當前無響應訊息
error nil, response 非nil，成功獲取響應訊息
error 非nil，接收響應出錯
*/
func (c *Client) RecvResponse() (response.TcaplusResponse, error)
4.1.7 傳送tcaplus同步請求並接受響應
/**
@brief 傳送tcaplus同步請求並接受響應
@param [IN] req tcaplus請求
@param [IN] timeout 超時時間
@retval response.TcaplusResponse tcaplus響應
@retval error 錯誤碼
error nil，response nil 成功但當前無響應訊息
error nil, response 非nil，成功獲取響應訊息
error 非nil，接收響應出錯
**/
func (c *Client) Do(req request.TcaplusRequest, timeout time.Duration) (response.TcaplusResponse, error)
4.2 TcaplusRequest介面
4.2.1 新增記錄
/**
@brief 向請求中新增一條記錄。
@param [IN] index 用於List操作(目前不支援)，通常>=0，表示該Record在所屬List中的Index；對於Generic操作，index無意義，設0即可
@retval record.Record 返回記錄指標
@retval error 錯誤碼
**/
AddRecord(index int32) (*record.Record, error)
4.2.2 設定請求非同步ID
/**
@brief 設定請求的非同步事務ID，api會將其值不變地通過對應的響應訊息帶回來
@param [IN] asyncId 請求對應的非同步事務ID
**/
SetAsyncId(id uint64)
4.2.3 設定版本校驗規則
/**
@brief 設定記錄版本的檢查型別，用於樂觀鎖
@param [IN] type 版本檢測型別，取值可以為(policy包中):
CheckDataVersionAutoIncrease: 表示檢測記錄版本號，只有當record.SetVersion函式傳入的引數version的值>0,並且版本號與伺服器端的版本號相同時，請求才會成功同時在伺服器端該版本號會自增1；如果record.SetVersion的version <=0，則仍然表示不關心版本號
NoCheckDataVersionOverwrite: 表示不檢測記錄版本號。當record.SetVersion函式傳入的引數version的值>0,覆蓋服務端的版本號；如果record.SetVersion的version <=0，則仍然表示不關心版本號
NoCheckDataVersionAutoIncrease: 表示不檢測記錄版本號，將伺服器端的資料記錄版本號自增1，若伺服器端新寫入資料記錄則新寫入的資料記錄的版本號為1
@retval error 錯誤碼
@note 此函式適合Replace, Update操作
**/
SetVersionPolicy(p uint8) error
4.2.4 設定響應標誌
/**
@brief 設定響應標誌。主要用於Generic表的insert、replace、update、delete操作。
@param [IN] flag 請求標誌:
0表示: 只需返回操作執行成功與否
1表示: 操作成功，響應返回與請求欄位一致
2表示: 操作成功，響應返回變更記錄的所有欄位最新資料
3表示: 操作成功，響應返回變更記錄的所有欄位舊資料
@retval error 錯誤碼
**/
SetResultFlag(flag int) error
4.2.5 部分欄位查詢和更新
/**
@brief 設定需要查詢或更新的Value欄位名稱列表，即部分Value欄位查詢和更新，可用於get、replace、update操作。
@param [IN] valueNameList 需要查詢或更新的欄位名稱列表
@retval error 錯誤碼
@note 在使用該函式設定欄位名時，欄位名只能包含value欄位名，不能包含key欄位名；對於陣列型別的欄位，refer欄位和陣列欄位要同時設定或者同時不設定，否則容易資料錯亂
**/
SetFieldNames(valueNameList []string) error
4.2.6 設定使用者快取
/**
@brief 設定使用者快取，響應訊息將攜帶返回
@param [IN] userBuffer 使用者快取
@retval error 錯誤碼
**/
SetUserBuff(userBuffer []byte) error
4.3 Record介面
4.3.1 SetKey/SetValue和GetKey/GetValue介面
通過KV介面，對記錄進行賦值(請求訊息)和獲取(響應訊息)
/**
@brief key欄位內容設定
@param [in] name 欄位名稱，最大長度32
@param [in] data 欄位內容
@retval error 錯誤碼
*/
func (r *Record) SetKeyInt8(name string, data int8) error
func (r *Record) SetKeyInt16(name string, data int16) error
func (r *Record) SetKeyInt32(name string, data int32) error
func (r *Record) SetKeyInt64(name string, data int64) error
func (r *Record) SetKeyFloat32(name string, data float32) error
func (r *Record) SetKeyFloat64(name string, data float64) error
func (r *Record) SetKeyStr(name string, data string) error
func (r *Record) SetKeyBlob(name string, data []byte) error
/**
@brief value欄位內容設定
@param [in] name 欄位名稱，最大長度32
@param [in] data 欄位內容
@retval error 錯誤碼
*/
func (r *Record) SetValueInt8(name string, data int8) error
func (r *Record) SetValueInt16(name string, data int16) error
func (r *Record) SetValueInt32(name string, data int32) error
func (r *Record) SetValueInt64(name string, data int64) error
func (r *Record) SetValueFloat32(name string, data float32) error
func (r *Record) SetValueFloat64(name string, data float64) error
func (r *Record) SetValueStr(name string, data string) error
func (r *Record) SetValueBlob(name string, data []byte) error
/**
@brief key欄位內容獲取
@param [in] name 欄位名稱，最大長度32
@retval data 欄位內容
@retval error 錯誤碼
*/
func (r *Record) GetKeyInt8(name string) (int8, error)
func (r *Record) GetKeyInt16(name string) (int16, error)
func (r *Record) GetKeyInt32(name string) (int32, error)
func (r *Record) GetKeyInt64(name string) (int64, error)
func (r *Record) GetKeyFloat32(name string) (float32, error)
func (r *Record) GetKeyFloat64(name string) (float64, error)
func (r *Record) GetKeyStr(name string) (string, error)
func (r *Record) GetKeyBlob(name string) ([]byte, error)
/**
@brief value欄位內容獲取
@param [in] name 欄位名稱，最大長度32
@retval data 欄位內容
@retval error 錯誤碼
*/
func (r *Record) GetValueInt8(name string) (int8, error)
func (r *Record) GetValueInt16(name string) (int16, error)
func (r *Record) GetValueInt32(name string) (int32, error)
func (r *Record) GetValueInt64(name string) (int64, error)
func (r *Record) GetValueFloat32(name string) (float32, error)
func (r *Record) GetValueFloat64(name string) (float64, error)
func (r *Record) GetValueStr(name string) (string, error)
func (r *Record) GetValueBlob(name string) ([]byte, error)
4.3.2 SetData和GetData介面
通過TDR結構體，對記錄進行賦值(請求訊息)和獲取(響應訊息)
/**
@brief 基於TDR描述設定record資料
@param [IN] data 基於TDR描述record介面資料，tdr的xml通過工具生成的go結構體，包含的TdrTableSt介面的一系列方法
@retval error 錯誤碼
*/
func (r *Record) SetData(data TdrTableSt) error
/**
@brief 基於TDR描述讀取record資料
@param [IN] data 基於TDR描述record介面資料，tdr的xml通過工具生成的go結構體，包含的TdrTableSt介面的一系列方法
@retval error 錯誤碼
**/
func (r *Record) GetData(data TdrTableSt) error
4.3.3 設定記錄版本號
/**
@brief 設定記錄版本號
@param [IN] v 資料記錄的版本號: <=0 表示不關注版本號不關心版本號。具體含義如下。
當CHECKDATAVERSION_AUTOINCREASE時: 表示檢測記錄版本號。
如果Version的值<=0,則仍然表示不關心版本號不關注版本號；
如果Version的值>0，那麼只有當該版本號與伺服器端的版本號相同時，
Replace, Update, Increase, ListAddAfter, ListDelete, ListReplace, ListDeleteBatch操作才會成功同時在伺服器端該版本號會自增1。
當NOCHECKDATAVERSION_OVERWRITE時: 表示不檢測記錄版本號。
如果Version的值<=0,則會把版本號1寫入服務端的資料記錄版本號(伺服器端成功寫入的資料記錄的版本號最少為1)；
如果Version的值>0，那麼會把該版本號寫入服務端的資料記錄版本號。
當NOCHECKDATAVERSION_AUTOINCREASE時: 表示不檢測記錄版本號，將伺服器端的資料記錄版本號自增1，若伺服器端新寫入資料記錄則新寫入的資料記錄的版本號為1。
**/
func (r *Record) SetVersion(v int32)
4.3.4 獲取記錄版本號
/**
@brief 獲取記錄版本號
@retval 記錄版本號
**/
func (r *Record) GetVersion() int32
4.4 TcaplusResponse介面
4.4.1 獲取響應結果
/*
@brief 獲取響應結果
@retval int tcaplus api自定義錯誤碼。 0，表示請求成功；非0,有錯誤碼，可從terror.GetErrMsg(int)得到錯誤訊息
*/
GetResult() int
4.4.2 獲取表名
/*
@brief 獲取響應表名
@retval string 響應訊息對應的表名稱
*/
GetTableName() string
4.4.3 獲取appId
/*
@brief 獲取響應appId
@retval uint64 響應訊息對應的appId
*/
GetAppId() uint64
4.4.4 獲取zoneId
/*
@brief 獲取響應zoneId
@retval uint32 響應訊息對應的zoneId
*/
GetZoneId() uint32
4.4.5 獲取響應命令字
/*
@brief 獲取響應命令
@retval int 響應訊息命令字，cmd包中的響應命令字
*/
GetCmd() int
4.4.6 獲取響應非同步ID
/*
@brief 獲取響應非同步id，和請求對應
@retval uint64 響應訊息對應的非同步id和請求對應
*/
GetAsyncId() uint64
4.4.7 獲取響應中記錄數
/*
@brief 獲取本響應中結果記錄條數
@retval int 響應中結果記錄條數
*/
GetRecordCount() int
4.4.8 獲取響應中一條記錄
/*
@brief 從結果中獲取一條記錄
@retval *record.Record 記錄指標
@retval error 錯誤碼
*/
FetchRecord() (*record.Record, error)
4.4.9 獲取響應中使用者快取資訊
/**
@brief 獲取響應訊息中的使用者快取資訊
@retval []byte 使用者快取二進位制，和請求訊息中的buffer內容一致
*/
GetUserBuffer() []byte
4.4.10 獲取響應中的序列號
/**
@brief 獲取響應訊息中的序列號
**/
GetSeq() int32
TcaplusDB是騰訊出品的分散式NoSQL資料庫，儲存和排程的程式碼完全自研。具備快取+落地融合架構、PB級儲存、毫秒級時延、無損水平擴充套件和複雜資料結構等特性。同時具備豐富的生態、便捷的遷移、極低的運維成本和五個九高可用等特點。客戶覆蓋遊戲、網際網路、政務、金融、製造和物聯網等領域。