輸入規格檔案

區塊鏈 App 產生器初始化命令會讀取輸入規格檔案，並使用數個工具產生鷹架式專案，以協助鏈碼開發處理作業。

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

如需有關指定記號資產的資訊，請參閱下列主題：
規格檔案可以 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:

特性類型

支援的基本特性類型如下：
  • 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:

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

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

 
validate:

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

這些驗證可以用逗號分隔開來鏈結。 

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

類型：字串
  • 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: 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。時區位移可取代 Z，如同在 -05:00 中央日光節約時間。 
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" (Go)。

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

如果完全未使用 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)"