开发指南(Go)

基于Go语言的接口手册

开发者能够使用Chain Connector连接链平台的Gateway模块，执行各种操作并访问链内数据。

Go语言版本Chain Connector的Git地址：https://github.com/taiyi-io/chain-connector-go

请使用Go 1.18或者更新版本编译

假定已经为应用配置了足够的访问权限，并且创建了访问令牌，令牌数据保存在token.json文件中，使用以下代码创建客户端并连接到接入网关"1.2.3.4:9090"

import sdk "github.com/taiyi-io/chain-connector-go"

var targetPath = "./token.json" 
connector, err := sdk.NewConnectorFromFile(targetPath)
if err != nil{
    log.fatalf("load connector fail: %s", err.Error())
    return
}
var gatewayHost = "1.2.3.4"
var gatewayPort = 9090
err = connector.Connect(gatewayHost, gatewayPort)
if err != nil{
    log.fatalf("connect gateway fail: %s", err.Error())
    return
}

创建成功后，应用就可以通过connector调用下列各种功能

数据范式管理

是否存在数据范式

检查指定数据范式是否存在系统中

var schemaName = "sample"
exists, err := connector.HasSchema(schemaName)
if err != nil{
    log.fatalf("check schema fail: %s", err.Error())
    return
}
if exists {
    log.printf("schema '%s' exists", schemaName)
}else{
    log.printf("schema '%s' not exists", schemaName)
}

创建数据范式

指定范式名称与属性列表创建新范式

var schemaName = "person"
var properties = []DocumentProperty{
    	{
			Name: "name",
			Type: PropertyTypeString,
		},
		{
			Name: "age",
			Type: PropertyTypeInteger,
		},
		{
			Name: "is_male",
			Type: PropertyTypeBoolean,
		},
}
if err = connector.CreateSchema(schemaName, properties); err != nil {
    log.fatalf("create schema fail: %s", err.Error())
    return
}
log.printf("schema '%s' creaeted", schemaName)

修改数据范式

更新指定范式的属性清单

var schemaName = "person"
var properties = []DocumentProperty{
    	{
			Name: "name",
			Type: PropertyTypeString,
		},
		{
			Name: "age",
			Type: PropertyTypeInteger,
		},
		{
			Name: "gender",
			Type: PropertyTypeString,
		},
}
if err = connector.UpdateSchema(schemaName, properties); err != nil {
    log.fatalf("update schema fail: %s", err.Error())
    return
}
log.printf("schema '%s' updated", schemaName)

删除数据范式

删除指定数据范式

var schemaName = "target"
err := connector.DeleteSchema(schemaName)
if err != nil{
    log.fatalf("delete schema fail: %s", err.Error())
    return
}
log.printf("schema '%s' deleted", schemaName)

获取数据范式

获取指定数据范式

var schemaName = "target"
schema, err := connector.GetSchema(schemaName)
if err != nil{
    log.fatalf("get schema fail: %s", err.Error())
    return
}

获取数据范式变更记录

获取指定数据范式的变更记录

var schemaName = "target"
version, logs, err := connector.GetSchemaLog(schemaName)
if err != nil{
    log.fatalf("get schema log fail: %s", err.Error())
    return
}

查询数据范式

以分页模式查询系统内数据范式

const offset = 9
const recordPerPage = 20
names, offset, limit, total, err := connector.QuerySchemas(offset, recordPerPage)
if err != nil{
    log.fatalf("query schemas fail: %s", err.Error())
    return
}
log.printf("%d / %d schemas returned", len(names), total)

数字资产管理

是否存在数字资产

检查指定数字资产是否存在系统中

const schemaName = "person"
const docID = "alice"
exists, err := connector.HasDocument(schemaName, docID)
if err != nil{
    log.fatalf("check document fail: %s", err.Error())
    return
}
if exists {
    log.printf("document '%s.%s' exists", schemaName, docID)
}else{
    log.printf("document '%s.%s' not exists", schemaName, docID)
}

创建数字资产

使用指定的标识和文档内容创建数字资产，如果不指定标识，则系统生成标识并返回调用者

const schemaName = "person"
const content = "{'name': 'alice', 'age': 18, 'career': 'nurse'}"
docID, err := connector.AddDocument(schemaName, "", content)
if err != nil{
    log.fatalf("add document fail: %s", err.Error())
    return
}
log.printf("document %s added", docID)

更新数字资产

更新指定数字资产的文档内容

const schemaName = "person"
const docID = "alice"
const content = "{'name': 'alice', 'age': 28, 'career': 'doctor'}"
err := connector.UpdateDocument(schemaName, docID, content)
if err != nil{
    log.fatalf("update document fail: %s", err.Error())
    return
}
log.printf("document %s updated", docID)

更新数字资产属性

更新目标数字资产的指定属性值

const schemaName = "person"
const docID = "alice"
const propertyName = "age"
err := connector.UpdateDocumentProperty(schemaName, docID, propertyName, PropertyTypeInteger, "18")
if err != nil{
    log.fatalf("update document property fail: %s", err.Error())
    return
}
log.printf("property of document %s updated", docID)

删除数字资产

删除指定数字资产

const schemaName = "person"
const docID = "bob"
err := connector.RemoveDocument(schemaName, docID)
if err != nil{
    log.fatalf("remove document fail: %s", err.Error())
    return
}
log.printf("document '%s.%s' removed", schemaName, docID)

获取数字资产

获取指定数字资产的文档内容

const schemaName = "person"
const docID = "alice"
content, err := connector.GetDocument(schemaName, docID)
if err != nil{
    log.fatalf("get document fail: %s", err.Error())
    return
}
log.printf("document '%s.%s' fetched", schemaName, docID)

查询数字资产

以分页模式查询指定范式包含的数字资产

const beginOffset = 9
const recordPerPage = 20
const schemaName = "person"
//查询条件
var condition QueryCondition
condition.
    MaxRecord(recordPerPage).
    SetOffset(beginOffset).
    PropertyGreaterOrEqual("age", "18").
    PropertyEqual("gender", "female")

documents, limit, offset, total, err := connector.QueryDocuments(schemaName, condition)
if err != nil{
    log.fatalf("query documents fail: %s", err.Error())
    return
}
log.printf("%d / %d documents returned", len(documents), total)

获取数字资产变更记录

获取指定数字资产的变更记录

const schemaName = "person"
const docID = "alice"
version, records, err := connector.GetDocumentLog(schemaName, docID)
if err != nil{
    log.fatalf("get document log fail: %s", err.Error())
    return
}
log.printf("document '%s.%s' log fetched", schemaName, docID)

智能合约管理

是否存在智能合约

检查指定智能合约是否存在系统中

const contractName = "new_car"
exists, err := connector.HasContract(contractName)
if err != nil{
    log.fatalf("check contract fail: %s", err.Error())
    return
}
if exists {
    log.printf("contract '%s' exists", contractName)
}else{
    log.printf("contract '%s' not exists", contractName)
}

部署智能合约

智能合约使用名称标识，部署合约时，指定名称和定义，如果没有同名合约，则新建，如果存在，则更新合约定义。

var define = ContractDefine{
    Steps: []ContractStep{
        {
            Action: "create_doc",
            Params: []string{"sample", "@1", "@2"},
        },
        {
            Action: "set_property",
            Params: []string{"sample", "catalog", "car"},
        },
        {
            Action: "set_property",
            Params: []string{"sample", "price", "556.50"},
        }, 
        {
            Action: "set_property",
            Params: []string{"sample", "color", "black"},
        },
        {
            Action: "update_doc",
            Params: []string{"@1", "sample"},
        },
        {
            Action: "submit",
        },
    },
}
const contractName = "new_car"
if err := connector.DeployContract(contractName, createContract); err != nil {
	log.fatalf("deploy contract fail: %s", err.Error())
    return
}
log.printf("smart contract '%s' deployed", contractName)

撤销智能合约

可以撤销指定名称的智能合约，撤销后该合约无法调用和访问

const contractName = "new_car"
if err := connector.WithdrawContract(contractName); err != nil {
	log.fatalf("withdraw contract fail: %s", err.Error())
    return
}
log.printf("smart contract '%s' withdrew", contractName)

执行智能合约

指定合约名称和启动参数，按照预设的合约步骤开始执行

var parameters = []string{
    "alice",
    "18",
    "blonde",
}
const contractName = "update_profile"
if err := connector.CallContract(contractName, parameters); err != nil {
	log.fatalf("call contract fail: %s", err.Error())
    return
}
log.println("call contract success")

开启合约追踪

对指定合约启用跟踪标志，能够查看各步骤执行情况

const contractName = "some_contract"
if err := connector.EnableContractTrace(contractName, parameters); err != nil {
	log.fatalf("enable contract trace fail: %s", err.Error())
    return
}
log.println("contract trace enabled")

屏蔽合约追踪

对指定合约关闭跟踪标志，禁止查看各步骤执行情况

const contractName = "some_contract"
if err := connector.DisableContractTrace(contractName, parameters); err != nil {
	log.fatalf("disable contract trace fail: %s", err.Error())
    return
}
log.println("contract trace disabled")

区块链管理

查询区块清单

查询指定高度范围的区块清单

const startHeight = 20
const endHeight = 40
idList, currentHeight, err := connector.QueryBlocks(startHeight, endHeight)
if err != nil{
    log.fatalf("query blocks fail: %s", err.Error())
    return
}
log.printf("%d block(s) available, current height %d", len(idList), currentHeight)

获取区块数据

指定区块ID，获取区块数据

const blockID = "abcdxxx..."
blockData, err := connector.GetBlock(blockID)
if err != nil{
    log.fatalf("get block fail: %s", err.Error())
    return  
}
log.println("get block success")

查询交易清单

分页模式查询指定区块内交易清单

const blockID = "abcdxxx..."
const startOffset = 15
const recordPerPage = 30
idList, offset, limit, total, err := connector.QueryTransactions(blockID, startOffset, recordPerPage)
if err != nil{
    log.fatalf("query transactions fail: %s", err.Error())
    return  
}
log.println("query transactions success")

获取交易数据

获取指定交易的详细数据

const blockID = "abcdxxx..."
const transID = "H123bb2"
transaction, err := connector.GetTransaction(blockID, transID)
if err != nil{
    log.fatalf("get transaction fail: %s", err.Error())
    return  
}
log.println("get transaction success")