1. 使用 Oracle Blockchain Platform
  2. 使用低程式碼區塊鏈 App 產生器建立鏈碼
  3. 使用 Visual Studio 程式碼適用的區塊鏈 App 產生器擴充
  4. 使用區塊鏈 App 產生器 VS 程式碼擴充功能建立鏈碼專案
  5. 輸入規格檔案

輸入規格檔案

Blockchain App Builder 初始化命令會讀取輸入規格檔案，並使用多種工具產生結構化專案，以協助鏈碼開發程序。

您可以使用規格檔案指定多個資產定義和行為、CRUD 和非 CRUD 方法宣告、自訂方法、引數驗證、自動封送處理 (Marshal) / 解除封送處理 (Unmarshal) 、通透保存功能，以及使用 SQL SELECT 或 CouchDB 查詢語言呼叫 RTF 資料查詢。將為您產生這些功能。

如需有關指定記號資產的資訊，請參閱下列主題：
規格檔可以 yaml 或 json 寫入。您可以在 Blockchain App Builder 套件下載中看到兩種格式的範例規格檔案：
  • Fabcar-Typescript.yml
  • Marbles-Go.yml

附註：

根據 Go 慣例，匯出的名稱以大寫字母開頭。因此，所有資產特性和方法的名稱必須在規格檔案中以大寫字母為開頭。

規格檔案的結構

一般而言，您會以下列方式建構規格檔案：

assets: 
    name:
    type:
    properties:
        name:
        type:
        id:
        derived:
           strategy:
           algorithm:
           format:
        mandatory:
        default:
        validate:
    methods:
        crud:
        others:
customMethods:

區塊鏈 App 產生器除了沒有指定類型的一般資產之外，還支援兩種特殊資產類型：內嵌資產和權杖資產。規格檔案之 assets: 區段下的特殊資產定義為 type: embedded 或 type: token。

表格 7-2 規格檔參數描述和範例

進入 描述 範例
assets:

此特性會採用資產的定義和行為。您可以在此處提供多個資產定義。

  
name:

資產的名稱。

下列名稱已保留。請勿將這些名稱用於資產。
  • account
  • role
  • hold
  • token
  • authorization
  • tokenAdmin
  • Account
  • Role
  • Hold
  • Token
  • Authorization
  • TokenAdmin
 
name: owner # Information about the owner
type:

資產類型

支援的特殊資產類型如下：
  • embedded
  • token

如果您未在 assets 區段中指定 type 參數，則資產為一般類型。

 
type:

類型：嵌入式

如果此特性設為 embedded，則會將資產定義為內嵌資產。內嵌資產沒有 CRUD 方法，而且必須是另一個資產的一部分，才能儲存在分類帳中。

在範例中，特性 address 是內嵌的，並且定義在其他資產中。

內嵌資產不支援循環參考。例如，在上一個範例中，address 資產不能包含 employee 資產的參照。

資產：employee
name: employee
  properties:
     name: employeeId
     type: string
     mandatory: true
     id: true

     name: firstName
     type: string
     validate: max(30)
     mandatory: true

     name: lastName
     type: string
     validate: max(30)
     mandatory: true

     name: age
     type: number
     validate: positive(),min(18)

     name: address
     type: address
資產：address
name: address

type: embedded

properties:
   name: street
   type: string

   name: city
   type: string

   name: state
   type: string

   name: country
   type: string
properties:

描述資產的所有特性。

  
name:

特性的名稱。

 
name: ownerId # Unique ID for each owner
id:
  • true

指定此資產的 ID。此為必要特性。

 
name: owner            # Information about the owner
properties:
     name: ownerId    # Unique ID for each owner
     type: string
     mandatory: true
     id: true
     name: name        # Name of the owner
     type: string
     mandatory: true
type:

特性類型 (Property types)

支援的基本特性類型：
  • number
  • float
  • string
  • boolean
  • date
  • array
對於 Go 鏈碼，number 對應至 int，float 對應至 float64。目前不支援其他類型，包含下列類型：
  • complex
  • unsigned/signed int
  • 8/16/32/64 bits
 
name: year        # Model year
                    type: number
                    mandatory: true
                    validate: min(1910),max(2020)
                    name: color       # Color - no validation as color names are innumerable
                    type: string
                    mandatory: true
derived:

此特性指定 ID 特性衍生自其他索引鍵。相依特性應為 string 資料類型，而非內嵌資產。

此特性有兩個必要參數：
  • strategy：採用 concat 或 hash 的值。
  • format：採用策略要使用的規格字串和值陣列。
範例 1：
  • 特性 employeeID 取決於 firstName 和 lastName 特性。
  • 此特性是 format 陣列中所列值的串連。
  • IND%1#%2%tIND 是陣列中的第 0 個索引，描述最終格式。
  • %n 是一個位置指定元，可從陣列中的其他索引取得其值。
  • %t 表示值應為來自通路表頭的 stub.timestamp。
  • 如果您需要在 format 字串中使用 % 字元，則應使用另一個 % 遁離該字元。
  • 此範例中的最終格式為：INDfirstName#lastName1606885454916IND
範例 2：
  • 使用 hash 時，您還必須使用 algorithm 參數。預設值為 sha256；也支援 md5。
  • IND%1#%2%t 是陣列中的第 0 個索引，描述最終格式。
  • %n 是一個位置指定元，可從陣列中的其他索引取得其值。
  • %t 表示值應為來自通路表頭的 stub.timestamp。
  • 如果您需要在 format 字串中使用 % 字元，則應使用另一個 % 遁離該字元。
範例 1
name: employee
  properties:
     name: employeeId
     type: string
     mandatory: true
     id: true
     derived:
         strategy: concat
         format: ["IND%1#%2%tIND","firstName","lastName"]

     name: firstName
     type: string
     validate: max(30)
     mandatory: true

     name: lastName
     type: string
     validate: max(30)
     mandatory: true

     name: age
     type: number
     validate: positive(),min(18)
範例 2
name: account
  properties:
     name: accountId
     type: string
     mandatory: true
     id: true
     derived:
         strategy: hash
         algorithm: 'sha256'
         format: ["IND%1#%2%t","bankName","ifsccode"]

     name: bankName
     type: string
     validate: max(30)
     mandatory: true

     name: ifsccode
     type: string
     mandatory: true
mandatory:
  • true
  • false

對應的特性為必要特性，無法在建立資產時略過。

 
name: phone       # Phone number - validate as (ddd)-ddd-dddd where dashes could also be periods or spaces
type: string
mandatory: true
validate: /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/
name: cars        # The list of car VINs owned by this owner
type: string[]
mandatory: false
default:

這會提供此特性的預設值。

  
validate:

指定的特性會根據 Blockchain App Builder 提供的部分立即可用驗證進行驗證。如果您確定鏈結有效，則可以鏈結驗證。

如果未提供 validate 特性，則只會對特性 type 進行驗證。

 
validate:

類型：數字
  • 正值 ()
  • 負 ()
  • min()
  • max()

這些驗證可以用逗號分隔在一起。 

name: offerApplied
type: number
validate: negative(),min(-4)
name: year  # Model year
type: number
mandatory: true
validate: min(1910),max(2020)
validate:

type：string (類型：字串)

  • min()
  • max()
  • email()
  • url()
  • /regex/ - 支援 PHP 正規表示式

對於 Go 鏈碼，應正確遁離包含特定保留字元或空格字元的正規表示式。

 
name: website 
type: string
mandatory: false
validate: url()
name: phone  # Phone number - validate as (ddd)-ddd-dddd where dashes could also be periods or spaces
type: string
mandatory: true
validate: /^\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/
name: Color #Color can be red, blue, or green
type: string
mandatory: true
validate: /^\\s*(red|blue|green)\\s*$/
validate:

類型：布林值
  • true
  • false

在範例中，特性 active 的驗證是依類型本身 (boolean) 驗證。 

name: active
type: boolean
validate:

type：array 類型

依類型本身，以 type: number[] 的形式表示陣列為數字類型。

您可以使用 number[1:5] 格式輸入陣列的限制，表示最小長度為 1，最大長度為 5。如果避免其中一項，則只會考慮最小值 / 最大值。 

name: items
type: number[:5]
validate:

類型：日期
  • min()
  • max()
日期應為下列其中一種格式：
  • YYYY-MM-DD
  • YYYY-MM-DDTHH:MM:SSZ，其中 T 會分隔日期與時間，而 Z 則表示 UTC。時區位移可以取代「中央日光節約時間」在 -05:00 中的 Z。 
name: expiryDate
type: date
validate: max('2020-06-26')
name: completionDate
type: date
validate: min('2020-06-26T02:30:55Z')
methods:

使用此項目來說明要產生的 CRUD (建立 / 讀取 / 更新 / 刪除) 或其他方法。

依預設，若未輸入任何內容，則會產生所有 CRUD 與其他方法。

 
methods:
    crud: [create, getById, update, delete]
    others: [getHistoryById, getByRange]
crud:
  • create
  • getByID (讀取)
  • update
  • delete

如果此陣列保留空白，將不會建立 CRUD 方法。

如果完全未使用 crud 參數，則預設會建立所有四個方法。

crud 參數不適用於 token 和 embedded 資產。 

methods:
    crud: [create, getById, delete]
    others: [] # no other methods will be created
others:
  • getHistoryById
  • getByRange

getHistoryById 會傳回清單中資產的歷史記錄。

getByRange 會傳回指定範圍內的所有資產。如需詳細資訊，請參閱 "getByRange" (TypeScript) 和 "GetByRange" (執行)。

如果此陣列保留空白，將不會建立其他方法。

如果完全未使用 others 參數，則預設會建立兩種方法。

others 參數不適用於 token 和 embedded 資產。 

methods:
    crud: [create, delete]
    others: [] # no other methods will be created
      methods:
        crud: [create, getById, update, delete]
        others: [getHistoryById, getByRange]
customMethods:

此特性會在主控制器檔案中建立可呼叫的自訂方法範本。它採用方法簽章，並在控制器檔案中建立函數宣告。

您可以在此處提供語言特定的函數宣告。

我們提供名為 executeQuery 的自訂方法。如果已將它新增至規格檔案，它會詳細說明如何執行 Berkeley DB SQL 和 CouchDB Rich Query。只有在連線至 Oracle Blockchain Platform Cloud 或 Enterprise Edition 時，才能呼叫此方法。

TypeScript

customMethods:
    - executeQuery
    - "buyCar(vin: string, buyerId: string, sellerId: string, price: number, date: Date)"
    - "addCar(vin: string, dealerId: string, price: number, date: Date)"

移至

customMethods:
    - executeQuery
    - "BuyCar(vin string, buyerId string, sellerId string, price int)"
    - "AddCar(vin string, dealerId string, price int)"