十、區塊鏈學習-Hyperledger Fabric (基於release-1.0) 鏈碼開發API總結

1. 文檔地址

https://godoc.org/gopkg.in/hyperledger/fabric.v1/core/chaincode/shim

2. 主要api

鏈碼主要通過shim.ChaincodeStub所提供的方法進行操作。

2.1 參數讀取API-GetFunctionAndParameters

函數： GetFunctionAndParameters：
作用：提取調用鏈碼交易中的方法名和參數，其中第一個參數是方法名稱，其他參數則爲函數入參
返回值：其返回值有兩個 第一個是 方法名 ，第二個是 入參的數組

func (stub *ChaincodeStub) GetFunctionAndParameters() (function string, params []string) 

比如在前面第八篇中的helloworld.go的實例中.

func (t *HelloWorld) Invoke(stub shim.ChaincodeStubInterface) peer.Response {
	// 通過GetFunctionAndParameters 來獲取到要調用的 函數 和 參數
	fn, args := stub.GetFunctionAndParameters()
	// 判斷是調用了哪個方法
	if (fn == "set"){
		return t.set(stub,args)
	}else if (fn == "get"){
		return t.get(stub,args)
	}
	// 如果不是 set 也不是 get 則報錯
	return shim.Error("Invoke err must set or get")
}

一般 會通過fn來分發請求到其他業務實現的函數中。

2.2 獲取鏈碼交易的參數API-GetStringArgs

函數： GetStringArgs：
作用：提取調用鏈碼交易中的參數
返回值：交易中的入參

func (stub *ChaincodeStub) GetStringArgs() []string

比如在前面第八篇中的helloworld.go的實例中.

// 實現接口方法
func (t *HelloWorld) Init(stub shim.ChaincodeStubInterface) peer.Response {
	// 通過GetStringArgs 獲取到輸入的參數
	args := stub.GetStringArgs()
	// 通過PutState 給srt 賦值 
	// 這樣就是 在初始化時 需要傳入兩個參數 一個是 srt  一個是 hellowrold 這樣就在初始化時個srt 賦值了helloworld
	err := stub.PutState(args[0],[]byte(args[1]))
	// 判斷是否報錯
	if (err != nil){
		return shim.Error(err.Error())
	}
	// 成功完成初始化
	return shim.Success(nil)
}

2.3 與賬本狀態交互的API

2.3.1 在賬本中增加鍵值對-PutState

函數： PutState：
參數：兩個參數 第一個是 key 第二個是value
作用：在賬本中增加或修改鍵值對
返回值：err

func (stub *ChaincodeStub) PutState(key string, value []byte) error

比如在前面第八篇中的helloworld.go的實例中.

// 通過PutState 給srt 賦值 
// 這樣就是 在初始化時 需要傳入兩個參數 一個是 srt  一個是 hellowrold 這樣就在初始化時個srt 賦值了helloworld
err := stub.PutState(args[0],[]byte(args[1]))

2.3.2 查找賬本中key對應的-GetState

函數： GetState：
參數：一個參數 要查詢的 key
作用：查找賬本中key對應的value
返回值：value的byte,err

func (stub *ChaincodeStub) GetState(key string) ([]byte, error)

比如在前面第八篇中的helloworld.go的實例中.

// 通過GetState 獲取srt值
value, err := stub.GetState(args[0])

2.3.3 刪除鍵值對-DelState

函數： DelState：
參數：一個參數 要刪除的 key
作用：刪除賬本中的某個鍵值對
返回值：err

func (stub *ChaincodeStub) DelState(key string) error

2.3.4 獲取指定範圍key的values-GetStateByRange

函數：GetStateByRange
參數：兩個 startKey 和 endKey
作用：刪除賬本中的某個鍵值對
返回值：返回值兩個 範圍內的value和 err

func (stub *ChaincodeStub) GetPrivateDataByRange(collection, startKey, endKey string) (StateQueryIteratorInterface, error)

這裏的區間爲[startKey,endKey)
也就是說

err := stub.PutState("srt1","1")
err := stub.PutState("srt2","2")
err := stub.PutState("srt3","3")

resultIterator,err := stub.GetStateByRange("srt1","str3")
defer resultIterator.Close();
for resultIterator.Next() {
	item, _ := resultIterator.Next();
	fmt.Printf(string(item.Value))
}

這裏會輸出1,2 不會輸出3

1
2

2.3.5 查詢某個key的歷史記錄-GetHistoryForKey

函數：GetHistoryForKey
參數：要查詢的key
作用：查詢某個key的歷史記錄
返回值：返回值兩個 key的歷史記錄 和 err

func (stub *ChaincodeStub) GetHistoryForKey(key string) (HistoryQueryIteratorInterface, error)

比如

historyIterator,err := stub.GetHistoryForKey("str")
defer historyIterator.Close();
 for historyIterator.Next() {
	item, _ := historyIterator.Next();
	fmt.Printf(string(item.TxId))
	fmt.Printf(string(item.Value))
}

2.3.6 創建複合鍵-CreateCompositeKey

函數：CreateCompositeKey
參數：創建複合鍵
作用：可以通過創建複合鍵來幫助區分某一類數據
返回值：複合鍵key 和 err

func (stub *ChaincodeStub) CreateCompositeKey(objectType string, attributes []string) (string, error)

比如

indexName := "sex~name"
indexKey, err := stub.CreateCompositeKey(indexName,[]string{"body","xiaowang"})
stub.PutState(indexKey,[]byte{0x00})
fmt.Printf(indexKey)
indexKey, err := stub.CreateCompositeKey(indexName,[]string{"girl","xiaoli"})
stub.PutState(indexKey,[]byte{0x00})
fmt.Printf(indexKey)

輸出
sex~nameboyxiaowang
sex~namegirlxiaoli

2.3.7 根據複合鍵某一局部值 查找匹配的數據以及拆分複合鍵-GetStateByPartialCompositeKey，SplitCompositeKey

函數：GetStateByPartialCompositeKey
參數：objectType-複合鍵 ，attributes-需匹配的參數
作用：查詢符合attributes要求的複合鍵的值
返回值：複合鍵key 和 err

func (stub *ChaincodeStub) GetStateByPartialCompositeKey(objectType string, attributes []string) (StateQueryIteratorInterface, error)

函數：SplitCompositeKey
參數：compositeKey-複合鍵
作用：拆分複合鍵 爲對應的屬性

func (stub *ChaincodeStub) SplitCompositeKey(compositeKey string) (string, []string, error)

比如查詢boy信息

indexName := "sex~name"
resultIterator,err := stub.GetStateByPartialCompositeKey(indexName ,[]string{"boy"})
defer resultIterator.Close();

for resultIterator.HasNext() {
	item,_ := resultIterator.Next()
	 objectType,compositeKeyParts,err := stub.SplitCompositeKey(item.Key)
	 fmt.Println("objectType:"+objectType)
 	 fmt.Println("sex:"+compositeKeyParts[0])
 	 fmt.Println("name:"+compositeKeyParts[1])
}

會輸出

objectType:sex~name
sex: boy
name:xiaowang

2.3.8 對數據庫進行查詢(1.0版本僅支持couchDB)-GetQueryResult

函數：GetQueryResult
參數：query-查詢指令
作用：對數據進行查詢 1.0版本僅支持couchDB
返回值：StateQueryIteratorInterface-返回結果集 error-錯誤信息

func (stub *ChaincodeStub) GetQueryResult(query string) (StateQueryIteratorInterface, error)

比如

resultIterator, err := stub.GetQueryResult("{\"selector\":\"sex\":\"boy\"}")

2.3.9 調用另一個鏈碼中的invoke方法-InvokeChaincode

函數：InvokeChaincode
參數：chaincodeName-鏈碼名稱 args-參數 channel-channel 名稱
作用： 調用另一個鏈碼中的invoke方法-
返回值：StateQueryIteratorInterface-返回結果集 error-錯誤信息

func (stub *ChaincodeStub) InvokeChaincode(chaincodeName string, args [][]byte, channel string) pb.Response

比如
調用chaincode_example002中的a向b轉賬

trans := [][]byte{[]byte("invoke"),[]byte("a"),[]byte("b"),[]byte("11")}
stub.InvokeChaincode("mycc",trans,"mychannel")